Update model card: add paper link, benchmark results, methodology, and Quick Start code

README.md

@@ -1,6 +1,6 @@
 ---
 license: apache-2.0
-base_model: unsloth/qwen2.5-7b-instruct-unsloth-bnb-4bit
+base_model: Qwen/Qwen2.5-7B-Instruct
 language:
 - en
 pipeline_tag: text-generation
@@ -8,14 +8,32 @@ tags:
 - humor
 - jokes
 - comedy
+- lora
+- sft
+- qwen2
+- unsloth
+- peft
 - causal-lm
 ---
 
 # HumorGen-7B
 
-**HumorGen-7B** is a humor generation model based on [Qwen2.5-7B-Instruct](https://huggingface.co/unsloth/qwen2.5-7b-instruct-unsloth-bnb-4bit), fine-tuned to generate funny jokes from headlines or topics.
+<p align="center">
+  <a href="https://edwardajayi.github.io/assets/papers/HumorGen_CSF.pdf">📄 Paper</a> •
+  <a href="https://huggingface.co/Jayi2424/HumorGen-7B">🤗 Model</a> •
+  <a href="https://github.com/edwardajayi">💻 GitHub</a>
+</p>
 
-## Quick Start
+**HumorGen-7B** is a 7B-parameter humor generation model fine-tuned from [Qwen/Qwen2.5-7B-Instruct](https://huggingface.co/Qwen/Qwen2.5-7B-Instruct) using the **Cognitive Synergy Framework** introduced in our paper. It is a LoRA adapter trained with Supervised Fine-Tuning (SFT) on high-quality humor data curated via a Mixture-of-Thought (MoT) approach with six cognitive personas grounded in psychological humor theory.
+
+This model achieves a Bradley-Terry rating of **1083.9** on automated pairwise evaluation, **outperforming Qwen-2.5-32B and GPT-OSS-120B on humor generation** despite being 4–17× smaller.
+
+> **Paper:** [HumorGen: Cognitive Synergy for Humor Generation in Large Language Models via Persona-Based Distillation](https://edwardajayi.github.io/assets/papers/HumorGen_CSF.pdf)
+> **Authors:** Edward Ajayi, Prasenjit Mitra — *Carnegie Mellon University Africa*
+
+---
+
+## 🚀 Quick Start (Colab / Jupyter)
 
 ```python
 # Install required packages
@@ -37,29 +55,45 @@ model = PeftModel.from_pretrained(base_model, "Jayi2424/HumorGen-7B")
 # Load tokenizer
 tokenizer = AutoTokenizer.from_pretrained("unsloth/qwen2.5-7b-instruct-unsloth-bnb-4bit")
 
-# Create a prompt for joke generation
+# Generate a joke
 prompt = "Generate a joke using the words 'Nigeria' and 'Capstone':\n"
-
-# Tokenize and generate
 inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
 outputs = model.generate(**inputs, max_new_tokens=100, use_cache=True)
-
-# Print the generated joke
 print(tokenizer.decode(outputs[0], skip_special_tokens=True))
 ```
 
-## Usage Examples
+---
+
+## 📖 Usage
 
-### Basic Generation
+### Standard Usage (Full Precision)
 
 ```python
-prompt = "Write a funny joke about: coffee"
-inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
-outputs = model.generate(**inputs, max_new_tokens=150, temperature=0.8)
-print(tokenizer.decode(outputs[0], skip_special_tokens=True))
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import PeftModel
+
+base_model_id = "Qwen/Qwen2.5-7B-Instruct"
+adapter_model_id = "Jayi2424/HumorGen-7B"
+
+tokenizer = AutoTokenizer.from_pretrained(base_model_id)
+model = AutoModelForCausalLM.from_pretrained(
+    base_model_id,
+    torch_dtype="auto",
+    device_map="auto"
+)
+model = PeftModel.from_pretrained(model, adapter_model_id)
+model = model.merge_and_unload()  # optional: merge for faster inference
+
+headline = "Denzel Washington reveals he doesn't watch movies anymore"
+messages = [{"role": "user", "content": f"Write a funny joke based on this news headline: {headline}"}]
+
+text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+inputs = tokenizer(text, return_tensors="pt").to(model.device)
+outputs = model.generate(**inputs, max_new_tokens=256, temperature=0.8, do_sample=True)
+print(tokenizer.decode(outputs[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True))
 ```
 
-### With System Prompt (Chat Format)
+### With System Prompt
 
 ```python
 SYSTEM_PROMPT = (
@@ -83,27 +117,75 @@ outputs = model.generate(
     do_sample=True,
     pad_token_id=tokenizer.eos_token_id,
 )
-
 print(tokenizer.decode(outputs[0][inputs.input_ids.shape[1]:], skip_special_tokens=True))
 ```
 
-## Model Details
+---
+
+## 🏆 Benchmark Results
+
+Evaluated on the **SemEval 2026 MWAHAHA** held-out test set (50 prompts, 43,048 pairwise comparisons judged by Llama-3.3-70B-Instruct):
 
-- **Base Model:** [Qwen2.5-7B-Instruct](https://huggingface.co/unsloth/qwen2.5-7b-instruct-unsloth-bnb-4bit)
-- **Architecture:** LoRA (Low-Rank Adaptation) adapter
-- **License:** Apache-2.0
-- **Language:** English
+| Model | BT Rating | Win % |
+|-------|-----------|-------|
+| GPT-5 | 1323.7 | 84.7% |
+| Kimi-K2 | 1221.6 | 75.3% |
+| Gemini-2.5-Pro | 1190.3 | 72.0% |
+| **HumorGen-SFT-7B (this model)** | **1083.9** | **59.5%** |
+| HumorGen-DPO-7B | 1079.9 | 59.0% |
+| GPT-OSS-120B | 989.2 | 47.7% |
+| Qwen-2.5-32B-Instruct | 964.3 | 44.5% |
+| Base Qwen-7B | 607.1 | 10.8% |
+
+> HumorGen-SFT-7B outperforms Qwen-2.5-32B and GPT-OSS-120B while being **4–17× smaller**.
+
+---
 
-## Generation Parameters
+## 🧠 Model Details
 
-| Parameter | Default | Description |
-|-----------|---------|-------------|
-| `max_new_tokens` | 100-512 | Maximum length of generated joke |
-| `temperature` | 0.7-0.8 | Controls creativity (higher = more random) |
+| Property | Value |
+|----------|-------|
+| Base Model | [Qwen/Qwen2.5-7B-Instruct](https://huggingface.co/Qwen/Qwen2.5-7B-Instruct) |
+| Fine-tuning Method | SFT (Supervised Fine-Tuning) |
+| Adapter Type | LoRA (r=16, alpha=16) |
+| Target Modules | q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj |
+| Training Framework | Unsloth + TRL |
+| Training Data | SemEval 2026 MWAHAHA (1,200 news headline prompts) |
+| BT Rating | 1083.9 (Win rate: 59.5%) |
+| License | Apache-2.0 |
+
+---
+
+## ⚙️ Generation Parameters
+
+| Parameter | Recommended | Description |
+|-----------|-------------|-------------|
+| `max_new_tokens` | 100–512 | Maximum length of generated joke |
+| `temperature` | 0.7–0.8 | Controls creativity (higher = more varied) |
 | `top_p` | 0.9 | Nucleus sampling threshold |
-| `do_sample` | True | Enable sampling for diverse outputs |
+| `do_sample` | `True` | Enable sampling for diverse outputs |
+
+---
+
+## 🔬 Training Methodology
+
+Data was synthesized using the **Cognitive Synergy Framework**:
+
+1. **Mixture-of-Thought (MoT):** Six distinct cognitive personas — *The Absurdist, The Cynic, The Neurotic, The Observer, The Wordsmith, The Optimist* — each generate 4 joke candidates per prompt from a teacher ensemble of Kimi-K2 and Qwen-2.5-32B-Instruct, yielding ~28,800 candidates across 1,200 prompts.
+2. **Elo Ranking:** All candidates are ranked via pairwise LLM evaluation using Llama-3.3-70B-Instruct as judge, producing per-prompt Elo ratings.
+3. **SFT Training:** The top-10 Elo-ranked candidates per prompt (12,000 total) are used to fine-tune the student model, promoting diversity across humor styles (wordplay, absurdity, sarcasm).
+
+---
+
+## 💡 Key Findings
+
+- **SFT is the strongest variant:** DPO and GRPO do not improve over the SFT baseline — cognitive data quality is the primary driver of humor generation performance.
+- **The Explainer Trap:** Training on reasoning traces hurts performance; the model learns to explain jokes rather than deliver them.
+- **Data > Scale:** A well-curated 7B student outperforms a 32B teacher and a 120B open-weight model.
+
+---
 
-## Citation
+## 📚 Citation
 
 If you use this model in your research, please cite: