Update README.md

README.md

@@ -105,3 +105,155 @@ Classifier prediction
 Architecture:
 ![Screenshot 2026-06-26 at 14.30.30](https://cdn-uploads.huggingface.co/production/uploads/6720d6553279dd0ff66c4995/hqHqkwOQtg1lY0RTQdxxE.png)
 
+Why Shared Encoder?
+
+Traditional guardrail systems may run:
+
+Language model
+Embedding model
+Classifier model
+Policy model
+This increases:
+
+CPU/GPU utilization
+latency
+memory consumption
+infrastructure complexity
+HomayShield avoids this by sharing the encoder.
+
+Advantages:
+
+Lower CPU usage
+Faster inference
+Lower memory footprint
+Better scalability
+Consistent semantic representation
+Supported Languages
+
+Current supported languages:
+
+Turkish (tr)
+English (en)
+Inference begins with language detection.
+
+If input language is unsupported:
+
+Reject or
+Skip evaluation
+Detection Strategy
+
+HomayShield combines two detection mechanisms.
+
+1) Semantic Detection
+
+Semantic similarity compares incoming prompt embeddings against known malicious attack embeddings.
+
+Useful for detecting:
+
+similar attacks
+prompt injection variants
+jailbreak attempts
+semantic anomalies
+adversarial patterns
+2) Classifier Detection
+
+Classifier predicts attack probability using shared embeddings.
+
+Useful for detecting:
+
+known attack patterns
+learned malicious behavior
+structured adversarial prompts
+Inference Modes
+
+HomayShield supports 3 inference strategies.
+
+Option 1 — OR Logic
+
+Security-first mode.
+
+if semantic_score >= semantic_threshold or classifier_score >= classifier_threshold:
+    ATTACK
+else:
+    NORMAL
+Best for:
+
+strict environments
+low false negatives
+Option 2 — Weighted Fusion
+
+Balanced mode.
+
+fusion_score = semantic_weight * semantic_score + classifier_weight * classifier_score
+Best for:
+
+balanced security
+tunable sensitivity
+Option 3 — Single Signal
+
+Choose one:
+
+semantic only
+classifier only
+Useful for benchmarking or lightweight deployments.
+
+Training Pipeline
+
+Training consists of 2 stages.
+
+Stage 1 — Encoder Training
+
+The encoder is trained using similarity learning.
+
+Goal:
+
+similar attacks cluster together
+similar normal prompts cluster together
+attacks and normal prompts separate clearly
+Loss:
+
+CosineEmbeddingLoss
+Stage 2 — Classifier Training
+
+After encoder training:
+
+embeddings are extracted
+classifier head is trained on embeddings
+Loss:
+
+BCEWithLogitsLoss
+Outputs:
+
+trained encoder
+trained classifier
+attack embedding bank
+normal embedding bank
+Training Command
+
+python training_final.py \
+  --train /home/asimyil/train.jsonl \
+  --output-dir /home/asimyil/HomayShield_v5
+Training Dataset
+
+HomayShield was trained using a large dataset of:
+
+benign prompts
+adversarial prompts
+Turkish prompts
+English prompts
+mixed-language prompts
+Dataset includes attack categories such as:
+
+Direct prompt injection
+Jailbreak attacks
+Instruction override
+Prompt leakage
+Data exfiltration
+Obfuscation attacks
+Multi-turn attacks
+Roleplay attacks
+Tool abuse
+Code injection
+Long context attacks
+Hard negative samples
+This helps improve detection robustness in real-world enterprise environments.