Upload README.md with huggingface_hub

README.md

@@ -1,126 +1,118 @@
 ---
-base_model: Qwen/Qwen2.5-7B-Instruct
-base_model_relation: finetune
-library_name: peft
+license: apache-2.0
+base_model: unsloth/qwen2.5-7b-instruct-unsloth-bnb-4bit
 language:
 - en
-license: apache-2.0
+pipeline_tag: text-generation
 tags:
 - humor
-- text-generation
-- lora
-- sft
-- peft
-- qwen2
-- transformers
-- unsloth
-pipeline_tag: text-generation
+- jokes
+- comedy
+- causal-lm
 ---
 
 # HumorGen-7B
 
-**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.
+**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.
 
-> **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)
-
----
-
-## Model Details
-
-| Property | Value |
-|---|---|
-| Base Model | 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%) |
-
----
-
-## How to Use
-
-This is a LoRA adapter. You need to load it on top of the base model using PEFT.
+## Quick Start
 
 ```python
-from transformers import AutoModelForCausalLM, AutoTokenizer
-from peft import PeftModel
+# Install required packages
+!pip install -q "unsloth[colab-new]" bitsandbytes xformers trl peft transformers
+!pip install -U bitsandbytes>=0.46.1
 
-base_model_id = "Qwen/Qwen2.5-7B-Instruct"
-adapter_model_id = "Jayi2424/HumorGen-7B"
+from peft import PeftModel
+from transformers import AutoModelForCausalLM, AutoTokenizer
 
-tokenizer = AutoTokenizer.from_pretrained(base_model_id)
-model = AutoModelForCausalLM.from_pretrained(
-    base_model_id,
-    torch_dtype="auto",
+# Load base model with 4-bit quantization (memory-efficient)
+base_model = AutoModelForCausalLM.from_pretrained(
+    "unsloth/qwen2.5-7b-instruct-unsloth-bnb-4bit",
     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}"}]
+# Load the HumorGen LoRA adapter
+model = PeftModel.from_pretrained(base_model, "Jayi2424/HumorGen-7B")
 
-text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
-inputs = tokenizer(text, return_tensors="pt").to(model.device)
+# Load tokenizer
+tokenizer = AutoTokenizer.from_pretrained("unsloth/qwen2.5-7b-instruct-unsloth-bnb-4bit")
 
-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))
-```
+# Create a prompt for joke generation
+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)
 
-## Training Data & Methodology
+# Print the generated joke
+print(tokenizer.decode(outputs[0], skip_special_tokens=True))
+```
 
-Data was synthesized using the **Cognitive Synergy Framework**:
+## Usage Examples
 
-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 of humor styles (wordplay, absurdity, sarcasm).
+### Basic Generation
 
----
+```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))
+```
 
-## Benchmark Results
+### With System Prompt (Chat Format)
 
-Evaluated on the SemEval 2026 MWAHAHA held-out test set (50 prompts, 43,048 pairwise comparisons judged by Llama-3.3-70B-Instruct):
+```python
+SYSTEM_PROMPT = (
+    "You are a joke generator. Given a headline or topic, generate a funny joke. "
+    "Output ONLY the joke text. No thinking tags, no reasoning, no explanation, no extra words."
+)
 
-| 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% |
+messages = [
+    {"role": "system", "content": SYSTEM_PROMPT},
+    {"role": "user", "content": "Write a funny joke about: Monday meetings"},
+]
 
-HumorGen-SFT-7B outperforms Qwen-2.5-32B and GPT-OSS-120B while being a 7B model.
+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=512,
+    temperature=0.7,
+    top_p=0.9,
+    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
 
-## Key Findings
+- **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
 
-- **SFT is the strongest variant:** DPO and O-GRPO do not improve over the SFT baseline, confirming that cognitive data quality is the primary driver of humor generation performance.
-- **The Explainer Trap:** Training on reasoning traces (CSD/Think variants) 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.
+## Generation Parameters
 
----
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `max_new_tokens` | 100-512 | Maximum length of generated joke |
+| `temperature` | 0.7-0.8 | Controls creativity (higher = more random) |
+| `top_p` | 0.9 | Nucleus sampling threshold |
+| `do_sample` | True | Enable sampling for diverse outputs |
 
 ## Citation
 
-If you use this model, please cite our paper:
+If you use this model in your research, please cite:
 
 ```bibtex
-@article{ajayi2025humorgen,
-  title     = {HumorGen: Cognitive Synergy for Humor Generation in Large Language Models via Persona-Based Distillation},
-  author    = {Ajayi, Edward and Mitra, Prasenjit},
-  year      = {2025},
-  institution = {Carnegie Mellon University Africa},
-  url       = {https://edwardajayi.github.io/assets/papers/HumorGen_CSF.pdf}
+@misc{ajayi2025humorgen,
+  title        = {HumorGen: Cognitive Synergy for Humor Generation in Large Language Models via Persona-Based Distillation},
+  author       = {Ajayi, Edward and Mitra, Prasenjit},
+  year         = {2025},
+  howpublished = {\url{https://edwardajayi.github.io/assets/papers/HumorGen_CSF.pdf}},
+  note         = {Preprint}
 }
 ```