Update README.md

README.md

@@ -1,39 +1,87 @@
-
 ---
 language:
 - en
 license: apache-2.0
 library_name: transformers
 base_model:
-  - mistralai/Mistral-Nemo-Base-2407
-  - Qwen/Qwen3-235B-A22B
+  - mistralai/Mistral-Nemo-Base-2407   # lightweight student
+  - Qwen/Qwen3-235B-A22B              # thinking + non-thinking teacher
+tags:
+- distillation
+- /think
+- /nothink
+- reasoning-transfer
+- arcee-ai
 ---
 
 ![Homunculus Logo](https://huggingface.co/arcee-ai/Homunculus/resolve/main/logo.jpg)
 
-## Overview
+# Arcee **Homunculus-12B**
 
-Arcee Homunculus is a 12B parameter model developed by Arcee.ai, based on the Mistral Nemo architecture.
+**Homunculus** is a 12 billion-parameter instruction model distilled from **Qwen3-235B** onto the **Mistral-Nemo** backbone.
+It was purpose-built to preserve Qwen’s two-mode interaction style—`/think` (deliberate chain-of-thought) and `/nothink` (concise answers)—while running on a single consumer GPU.
 
-It was produced by distilling of Qwen3 235B logits onto Mistral Nemo after tokenizer replacement.
+---
 
-Like Qwen3, it features both thinking and non-thinking modes. As suggested by the name, it is a weird little guy produced through alchemy.
+## ✨ What’s special?
 
-Homunculus is a surprisingly powerful model for its size, showing strong performance in real-world applications despite being able to fit on consumer GPUs.
+| Feature                           | Detail                                                                                                                                               |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Reasoning-trace transfer**      | Instead of copying just final probabilities, we align *full* logit trajectories, yielding more faithful reasoning.        |
+| **Total-Variation-Distance loss** | To better match the teacher’s confidence distribution and smooth the loss landscape. |
+| **Tokenizer replacement**         | The original Mistral tokenizer was swapped for Qwen3's tokenizer.                          |
+| **Dual interaction modes**        | Use `/think` when you want transparent step-by-step reasoning (good for analysis & debugging). Use `/nothink` for terse, production-ready answers. Most reliable in the system role field.   |                    |
 
+---
 
-## Basic use
+## 🔧 Quick Start
 
-```
+```python
+from transformers import AutoTokenizer, AutoModelForCausalLM
 
-# Use a pipeline as a high-level helper
+model_id = "arcee-ai/Homunculus"
+tokenizer = AutoTokenizer.from_pretrained(model_id)
+model = AutoModelForCausalLM.from_pretrained(
+    model_id, 
+    torch_dtype="auto",
+    device_map="auto"
+)
 
-from transformers import pipeline
-
-pipe = pipeline("text-generation", model="arcee-ai/Homunculus")
-messages = \[
-{"role": "user", "content": "Who are you?"},
+# /think mode - Chain-of-thought reasoning
+messages = [
+    {"role": "system", "content": "You are a helpful assistant. /think"},
+    {"role": "user", "content": "Why is the sky blue?"},
 ]
-pipe(messages)
+output = model.generate(
+    tokenizer.apply_chat_template(messages, tokenize=True, return_tensors="pt"),
+    max_new_tokens=512,
+    temperature=0.7
+)
+print(tokenizer.decode(output[0], skip_special_tokens=True))
 
+# /nothink mode - Direct answers
+messages = [
+    {"role": "system", "content": "You are a helpful assistant. /nothink"},
+    {"role": "user", "content": "Summarize the plot of Hamlet in two sentences."},
+]
+output = model.generate(
+    tokenizer.apply_chat_template(messages, tokenize=True, return_tensors="pt"),
+    max_new_tokens=128,
+    temperature=0.7
+)
+print(tokenizer.decode(output[0], skip_special_tokens=True))
 ```
+
+## 💡 Intended Use & Limitations
+
+Homunculus is designed for:
+
+* **Research** on reasoning-trace distillation, Logit Imitation, and mode-switchable assistants.
+* **Lightweight production** deployments that need strong reasoning at <12 GB VRAM.
+
+### Known limitations
+
+* May inherit biases from the Qwen3 teacher and internet-scale pretraining data.
+* Long-context (>32 k tokens) use is experimental—expect latency & memory overhead.
+
+---