Upload README.md with huggingface_hub

README.md

@@ -30,6 +30,34 @@ On free-form tasks a model's own confidence is a weak signal of correctness. Thi
 
 A positive gain means this adapter detects the model's errors **better than the model's own confidence.**
 
+## Usage
+```python
+import torch, torch.nn as nn
+from safetensors.torch import load_file
+from huggingface_hub import hf_hub_download
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+BASE = "Qwen/Qwen-AgentWorld-35B-A3B"
+REPO = "FINAL-Bench/metacog-adapter-Qwen-AgentWorld-35B-A3B"
+
+tok = AutoTokenizer.from_pretrained(BASE)
+model = AutoModelForCausalLM.from_pretrained(BASE, dtype="auto", device_map="auto").eval()
+
+# Metacognition adapter = base model's last hidden state -> P(this answer is wrong). Base stays frozen.
+d = model.config.hidden_size
+adapter = nn.Sequential(nn.LayerNorm(d), nn.Linear(d, d // 4), nn.GELU(), nn.Dropout(0.1), nn.Linear(d // 4, 1))
+adapter.load_state_dict(load_file(hf_hub_download(REPO, "adapter.safetensors")))
+adapter.eval().to(model.device, dtype=torch.float32)
+
+prompt = "..."  # your question / task
+ids = tok.apply_chat_template([{"role": "user", "content": prompt}],
+                              return_tensors="pt", add_generation_prompt=True).to(model.device)
+with torch.no_grad():
+    h = model(ids, output_hidden_states=True).hidden_states[-1][0, -1].float()
+    p_wrong = torch.sigmoid(adapter(h)).item()
+print(f"P(model is about to be wrong) = {p_wrong:.3f}")   # higher => defer / double-check / escalate
+```
+
 ## Files
 - `adapter.safetensors` — adapter weights (base model frozen)
 - `config.json` — metadata (base model, hidden size)