Update model card — v7: 85 features, 254K params, F1 0.950, 6-dataset

README.md

@@ -1,19 +1,38 @@
 ---
-language: en
+language:
+  - en
 license: mit
 library_name: phishbyte
 pipeline_tag: text-classification
 tags:
   - phishing-detection
   - email-security
+  - cybersecurity
+  - security
   - pytorch
   - from-scratch
   - no-pretrained-weights
   - cascading-inference
   - lightweight
   - explainable-ai
+  - nlp
+  - phishing
+  - spam-detection
+  - malware-detection
+  - threat-detection
+  - email-classification
+  - text-classification
+  - feature-engineering
+  - interpretable-ml
+  - tfidf
+  - residual-network
 datasets:
-  - CEAS-2008
+  - ceas-2008
+  - enron-email
+  - spamassassin
+  - ling-spam
+  - nazario-phishing
+  - nigerian-fraud
 metrics:
   - f1
   - precision
@@ -26,102 +45,146 @@ model-index:
           type: text-classification
           name: Phishing Email Detection
         dataset:
-          name: CEAS-2008
+          name: 6-corpus benchmark (CEAS, Enron, SpamAssassin, Ling-Spam, Nazario, Nigerian)
           type: ceas-2008
         metrics:
           - type: f1
-            value: 0.948
+            value: 0.9503
+            name: F1 Score
           - type: accuracy
-            value: 0.944
+            value: 0.9494
+            name: Accuracy
           - type: precision
-            value: 0.954
+            value: 0.9490
+            name: Precision
           - type: recall
-            value: 0.943
+            value: 0.9516
+            name: Recall
+widget:
+  - text: "From: PayPal Security <security@paypa1-alert.tk>\nReply-To: attacker@evil-domain.ru\nSubject: URGENT: Your account will be suspended\n\nDear Customer, your PayPal account has been suspended. Verify now at http://paypal-login.tk/verify"
+    example_title: "Phishing email"
+  - text: "From: alice@company.com\nReply-To: alice@company.com\nSubject: Team lunch tomorrow\n\nHi everyone, lunch is at noon tomorrow. See you there!"
+    example_title: "Legitimate email"
 ---
 
-# Phish_Byte
+# Phish_Byte v7
 
 A from-scratch PyTorch model for **email phishing detection**.
-**F1 0.948** on CEAS-2008. **12,545 parameters** (≈9,000× smaller than DistilBERT).
-**1,500+ emails/sec** on a laptop GPU. Every verdict explains itself.
 
-## Why this exists
+**F1 0.950** on 5,000 held-out samples from a 6-corpus benchmark.
+**254K parameters** (≈260× smaller than DistilBERT).
+**995 emails/sec** on a laptop GPU.
+**85 engineered features** (35 rule-based + 50 TF-IDF learned from corpus).
+Every verdict explains itself with full per-feature attribution.
 
-Every phishing detection model on HuggingFace is currently a fine-tuned
-transformer (DistilBERT, BERT, RoBERTa) — 65 to 110 million parameters,
-~250 MB on disk, ~50 ms per email on GPU. Phish_Byte takes a different
-bet: a small custom MLP trained from scratch, fed by 29 carefully chosen
-features, routed through a cascading inference pipeline. The model is
-**9,000× smaller** than DistilBERT, performs competitively, deploys
-without a GPU, and explains every decision.
+> **The only non-transformer phishing detection model on HuggingFace.**
 
-## Usage
+## Quick start
 
 ```python
 from phishbyte import PhishByteEngine
 
-engine  = PhishByteEngine.from_pretrained("AnonymousSingh-007/phishbyte")
+engine  = PhishByteEngine.from_pretrained("SamSec007/phishbyte")
 verdict = engine.analyze(raw_email_string)
 
-print(verdict.label)             # 'phishing'
+print(verdict.label)             # "phishing"
 print(verdict.probability)       # 0.9735
-print(verdict.confidence)        # 'high'
-print(verdict.layer_used)        # 2 — MLP made this call
-print(verdict.feature_weights)   # full per-feature attribution
+print(verdict.confidence)        # "high"
+print(verdict.layer_used)        # 2
+print(verdict.feature_weights)   # 85-feature attribution
 ```
 
+## Analyse a real email from Gmail
+
+1. Open the email in Gmail
+2. Click ⋮ → **Show original**
+3. Copy all (Ctrl+A, Ctrl+C)
+
+```python
+engine = PhishByteEngine.from_pretrained("SamSec007/phishbyte")
+verdict = engine.analyze(pasted_raw_email)
+print(verdict)
+```
+
+Or save as `.eml` and run:
+
+```bash
+python cli.py --file suspicious.eml
+```
+
+## What changed in v7
+
+- **85 features** (was 29) — added 50 TF-IDF unigrams + 3 BDI features + 2 domain features + 1 composite
+- **254K parameters** (was 12K) — deeper residual MLP with two ResBlocks and input skip connection
+- **6-dataset training** (was CEAS-2008 only) — Enron, SpamAssassin, Ling-Spam, Nazario, Nigerian Fraud
+- **TF-IDF vocabulary** — 50 most discriminative unigrams learned from training corpus. No pretrained LM.
+- **Body Domain Identification** — most common link domain mismatch, form action mismatch, external link ratio
+- **Display name spoofing** — catches "PayPal Security" \<attacker@evil.com\>
+- **Calibrated training metrics** — F1 at Youden-optimal threshold, not naive 0.5 cutoff
+
 ## Architecture
 
 ```
-Layer 1 — rule scorers (~1 ms): domain + URL + SPF + subject
-            │
-            ├──► obvious phishing? short-circuit verdict
-            │
-            └──► otherwise route to MLP
-                       │
-Layer 2 — MLP (~3 ms): 29 → 96 → 48 → 1 (sigmoid)
-            │
-            ▼
-        PhishVerdict {label, probability, confidence, layer_used, feature_weights}
+raw email
+  → Layer 1 (6 rule scorers, ~1ms) → veto gate (obvious phishing only)
+  → Layer 2 (residual MLP, ~3ms)
+      85 → 360 → 180 (×2 ResBlock) → 90 → 48 → 1 (sigmoid)
+      + input-to-output skip connection
+  → PhishVerdict {label, probability, confidence, layer_used, feature_weights}
 ```
 
-## Performance (CEAS-2008, n=2000 held-out)
+## Benchmarks (5,000 held-out, 6-corpus)
+
+| Metric | Phish_Byte v7 | DistilBERT fine-tuned |
+|--------|:------------:|:---------------------:|
+| F1 score | **0.950** | ~0.967 |
+| Accuracy | **94.94%** | ~97% |
+| Parameters | **254K** | 66,000,000 |
+| Model size | **~1 MB** | ~263 MB |
+| Throughput (GPU) | **995/sec** | ~50/sec |
+| GPU required | **No** | Practically yes |
+| Header + SPF analysis | **Yes** | No |
+| Per-feature attribution | **85 features** | Token-level SHAP |
+
+## Feature groups (85 total)
 
-| Metric           | Value     |
-|------------------|----------:|
-| F1 score         | **0.948** |
-| Accuracy         | 94.40%    |
-| Precision        | 0.9537    |
-| Recall           | 0.9432    |
-| Parameters       | 12,545    |
-| Model size       | ~50 KB    |
-| Throughput (GPU) | 1,527 /s  |
-| Throughput (CPU) | ~800 /s   |
+| Group | Count | Examples |
+|-------|:-----:|---------|
+| Domain | 7 | mismatch, Reply-To diff, brand impersonation, display name spoof, suspicious pattern |
+| URL + Body | 10 | HTTPS ratio, anchor mismatch, urgency (normalized), caps ratio, digit ratio |
+| SPF | 3 | fail, no record, no IP |
+| Subject | 7 | urgency, security theme, brand, currency, all caps, fake RE, fake txn ID |
+| BDI | 3 | most common link domain mismatch, form action mismatch, external link ratio |
+| TF-IDF | 50 | top-50 discriminative unigrams from training corpus |
+| Composite | 5 | per-module layer scores |
 
-## Features (29 inputs)
+## Training data
 
-- **Domain (5)**: From/Reply-To/Return-Path mismatch, freemail flag, brand impersonation
-- **URL (5)**: HTTPS ratio, anchor mismatch, suspicious TLD, urgency, link density
-- **SPF (3)**: SPF fail, no record, no sending IP
-- **Subject (7)**: urgency, security theme, brand name, currency, all caps, fake RE, fake transaction ID
-- **Character-level (5)**: caps ratio, digit ratio, special chars, avg word length, HTML/text ratio
-- **Composite (4)**: per-layer normalized scores
+CEAS-2008 + Enron + SpamAssassin + Ling-Spam + Nazario + Nigerian Fraud = **~83K emails** (balanced 50/50).
+
+Same 6-corpus benchmark used by the top DistilBERT model on HuggingFace.
+
+## Install
+
+```bash
+pip install huggingface_hub safetensors dnspython
+```
 
 ## Limitations
 
-- ~5% of decisions are wrong (F1 0.948, not 1.0). Use as one signal in defence-in-depth, not the only gate.
-- Trained on CEAS-2008 — English-language phishing from 2008. Modern attack patterns and non-English emails will degrade performance.
-- SPF validation is bypassed for training (historical domains don't resolve) but runs live at inference time.
-- Adversarial emails crafted specifically to game these features will get through.
+- ~5% error rate. Use as one signal in defence-in-depth.
+- Trained on English-language phishing (2003–2008 era). Modern attacks and non-English emails will degrade recall.
+- SPF validation skipped for training (historical domains). Re-enables at inference on live emails.
+- TF-IDF vocabulary is corpus-specific. Retrain on your own data for best domain fit.
 
 ## Citation
 
 ```bibtex
 @software{phishbyte2026,
-  author  = {Singh, Samratth},
-  title   = {Phish_Byte: A cascading from-scratch PyTorch model for email phishing detection},
-  year    = {2026},
-  url     = {https://github.com/AnonymousSingh-007/Phish_Byte}
+  author = {Singh, Samratth},
+  title  = {Phish_Byte: Cascading from-scratch PyTorch phishing detection},
+  year   = {2026},
+  url    = {https://github.com/AnonymousSingh-007/Phish_Byte}
 }
 ```