Update README.md

README.md

@@ -1,3 +1,96 @@
 ---
-license: apache-2.0
+license: mit
+library_name: peft
+pipeline_tag: text-generation
+language:
+  - en
+tags:
+  - lora
+  - peft
+  - adapter
+  - safety
+  - alignment
+  - jailbreak-robustness
+base_model:
+  - meta-llama/Llama-3.1-8B-Instruct
+  - Qwen/Qwen2.5-7B-Instruct
+base_model_relation: adapter
 ---
+
+<h1 align="center">HARC: Coupling Harmfulness and Refusal Directions for Robust Safety Alignment</h1>
+
+<p align="center">
+  <a href="https://arxiv.org/abs/2607.00572"><img src="https://img.shields.io/badge/Paper-arXiv-b31b1b.svg?logo=arxiv&logoColor=white" alt="Paper"></a>
+  <a href="https://huggingface.co/microsoft/HARC"><img src="https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Models-yellow.svg" alt="Hugging Face"></a>
+  <a href="https://github.com/microsoft/HARC"><img src="https://img.shields.io/badge/GitHub-Code-181717.svg?logo=github" alt="GitHub"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT"></a>
+</p>
+
+---
+
+**HARC (Harmfulness-And-Refusal Coupling)** is a representation-level safety-alignment method that binds a model's internal harmfulness and refusal directions so that detecting harm reliably triggers refusal at both prompt and response positions in the residual stream. By confining the intervention to this low-dimensional harmfulness–refusal subspace, HARC strengthens robustness to jailbreak attacks while leaving general capability and over-refusal behavior largely intact. This repo provides the official implementation of our paper *HARC: Coupling Harmfulness And Refusal Directions for Robust Safety Alignment*.
+
+
+## Model description
+
+HARC couples a model's internal *harmfulness* and *refusal* directions at both
+prompt-side and response-side token positions, using an additive margin-hinge
+loss on cosine projections of the residual stream. The intervention is confined
+to a low-dimensional harmfulness–refusal subspace within a small set of selected
+layers, which improves robustness to jailbreak attacks while preserving general
+capability and avoiding the over-refusal regression typical of broader safety
+tuning.
+
+The LoRA adapter (rank 32, alpha 64) is applied to attention and MLP projections
+and trained for up to 4,000 steps with a composite objective: (i) the
+margin-hinge coupling loss, (ii) a KL-divergence retention term anchoring benign
+outputs to the base model, and (iii) a cross-entropy term supervising refusal
+text on harmful prompts. Training directions are extracted via
+difference-of-means on contrastive prompt sets and periodically recomputed with
+EMA blending. The adapter adds ~1% trainable parameters and leaves the base
+architecture unchanged.
+
+This release accompanies the HARC paper. Training and evaluation code: https://github.com/microsoft/HARC
+
+## How to use
+
+These are PEFT adapters — load the base model, then attach the adapter with the
+matching `subfolder`.
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import PeftModel
+
+base_id = "Qwen/Qwen2.5-7B-Instruct"          # or "meta-llama/Llama-3.1-8B-Instruct"
+subfolder = "harc_qwen2.5_7b"                  # or "harc_llama3.1_8b"
+
+tokenizer = AutoTokenizer.from_pretrained(base_id)
+base = AutoModelForCausalLM.from_pretrained(base_id, torch_dtype="auto", device_map="auto")
+model = PeftModel.from_pretrained(base, "microsoft/HARC", subfolder=subfolder)
+
+messages = [{"role": "user", "content": "Hello!"}]
+inputs = tokenizer.apply_chat_template(messages, add_generation_prompt=True, return_tensors="pt").to(model.device)
+out = model.generate(inputs, max_new_tokens=256)
+print(tokenizer.decode(out[0][inputs.shape[-1]:], skip_special_tokens=True))
+```
+
+Use the base model's standard chat template. Inference hardware requirements
+match the base model (a 7–8B model in bf16/fp16 fits on a 24GB GPU). Requires
+`torch >= 2.1`, `transformers`, and `peft`.
+
+## Results
+
+<p align="center">
+  <img src="assets/HARC-res.png" alt="HARC main results on Llama-3.1-8B and Qwen-2.5-7B" width="60%">
+</p>
+
+## Citation
+
+```bibtex
+@article{chua2026harc,
+  title={HARC: Coupling Harmfulness and Refusal Directions for Robust Safety Alignment},
+  author={Chua, Shei Pern and Wu, Fangzhao},
+  journal={arXiv preprint arXiv:2607.00572},
+  year={2026}
+}
+```