Update README.md

README.md

@@ -1,21 +1,182 @@
 ---
-base_model: unsloth/Qwen3-30B-A3B-Instruct-2507
+base_model: Qwen/Qwen3-30B-A3B-Instruct-2507
 tags:
 - text-generation-inference
 - transformers
 - unsloth
 - qwen3_moe
+- cognitive chains 
+- cognition 
 license: apache-2.0
 language:
 - en
+datasets:
+- Daemontatox/SOCAM
+library_name: transformers
 ---
 
-# Uploaded finetuned  model
+## Daemontatox/SOCAM-V1
 
-- **Developed by:** Daemontatox
-- **License:** apache-2.0
-- **Finetuned from model :** unsloth/Qwen3-30B-A3B-Instruct-2507
+### Model Description
 
-This qwen3_moe model was trained 2x faster with [Unsloth](https://github.com/unslothai/unsloth) and Huggingface's TRL library.
+SOCAM-V1 (Social Cognitive Agent Model – V1) is a fine-tuned large language model built on top of Qwen/Qwen3-30B-A3B-Instruct.
 
-[<img src="https://raw.githubusercontent.com/unslothai/unsloth/main/images/unsloth%20made%20with%20love.png" width="200"/>](https://github.com/unslothai/unsloth)
+The model is trained to function as a Cognitive State Machine, extracting cognitive chains from natural social utterances based on Theory of Mind (ToM) reasoning.
+
+Each cognitive chain follows the structure:
+
+Situation ⇒ Clue ⇒ Thought ⇒ (Action + Emotion)
+
+This provides an interpretable representation of a user’s cognitive state, supporting applications in dialogue systems, emotional support agents, and multi-agent cognitive architectures.
+
+
+---
+
+### Training Details
+
+Base Model: Qwen/Qwen3-30B-A3B-Instruct
+
+Fine-tuning Method: QLoRA with Unsloth + TRL
+
+Dataset: Daemontatox/SOCAM
+
+Adapted from the COKE dataset (Wu et al., 2024)
+
+~45k structured samples with fields: situation, clue, thought, action, emotion
+
+Emotions restricted to: Love, Surprise, Joyful, Sad, Angry, Fearful
+
+
+### Training Parameters:
+
+Sequence length: 2048
+
+LoRA config: r=16, alpha=32, dropout=0.01
+
+Optimizer: AdamW (8-bit)
+
+Effective batch size: 256 (16 × grad acc 16)
+
+Learning rate: 2e-4 (cosine schedule, warmup ratio 0.02)
+
+Epochs: 2
+
+
+Hardware: H100-class GPU (8-bit quantization for feasibility)
+
+
+
+---
+
+### Model Capabilities
+
+Converts free-text utterances into structured cognitive chains.
+
+Ensures separation of:
+
+Situation (context domain)
+
+Clue (triggering factor)
+
+Thought (internal cognition)
+
+Action (behavioral response)
+
+Emotion (affective category)
+
+
+Outputs deterministic JSON for easy downstream parsing.
+
+
+
+---
+
+⁶
+### Example Usage
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+import torch
+
+model = AutoModelForCausalLM.from_pretrained(
+    "Daemontatox/SOCAM-V1",
+    device_map="auto",
+    torch_dtype=torch.bfloat16
+)
+tokenizer = AutoTokenizer.from_pretrained("Daemontatox/SOCAM-V1")
+
+prompt = """Situation: "I have an important exam tomorrow."
+Clue: "I have studied consistently for weeks."
+"""
+
+inputs = tokenizer(prompt, return_tensors="pt").to("cuda")
+outputs = model.generate(**inputs, max_new_tokens=256)
+print(tokenizer.decode(outputs[0], skip_special_tokens=True))
+
+Expected output:
+
+{
+  "situation": "I have an important exam tomorrow.",
+  "clue": "I have studied consistently for weeks.",
+  "thought": "I believe I will perform well and feel confident.",
+  "action": "I review lightly and get proper rest.",
+  "emotion": "Joyful"
+}
+
+```
+
+---
+
+### Limitations & Risks
+
+The model may misclassify ambiguous emotions (e.g., Sad vs Fearful).
+
+Outputs depend on the quality of the SOCAM dataset and may reflect dataset biases.
+
+Not suitable for clinical or medical use.
+
+Always validate JSON outputs before downstream use.
+
+
+
+---
+
+### Intended Uses
+
+Research on machine Theory of Mind (ToM).
+
+Multi-agent cognitive architectures (Tracker, Updater, Reviewer, Responder).
+
+Dialogue systems requiring interpretable cognitive reasoning.
+
+
+Not intended for:
+
+Clinical diagnostics
+
+Sensitive decision-making without human oversight
+
+
+
+---
+
+### Citation
+
+If you use this model, please cite:
+
+@misc{socam2025,
+  title   = {SOCAM-V1: A Cognitive State Machine for Theory of Mind Reasoning},
+  author  = {Ammar Alnagar},
+  year    = {2025},
+  howpublished = {\url{https://huggingface.co/Daemontatox/SOCAM-V1}}
+}
+
+
+---
+
+### Acknowledgments
+
+Base model: Qwen/Qwen3-30B-A3B-Instruct
+
+Dataset foundation: COKE (Wu et al., 2024)
+
+Training libraries: Unsloth, TRL, Hugging Face Transformers