Add model card with schema and sample IO

README.md

@@ -0,0 +1,350 @@
+---
+language:
+- en
+- ms
+- zh
+- ta
+license: other
+library_name: transformers
+pipeline_tag: text-generation
+tags:
+- qwen2.5
+- lora
+- malaysia
+- safety
+- moderation
+- rukun-negara
+- multilingual
+base_model: Qwen/Qwen2.5-32B-Instruct
+model-index:
+- name: qwen25-32b-rukun-v1-merged
+  results:
+  - task:
+      type: text-generation
+      name: Structured safety validation (Rukun Negara)
+    dataset:
+      type: custom
+      name: benchmark_data (50 labeled prompts)
+    metrics:
+    - type: accuracy
+      value: 0.88
+    - type: precision
+      value: 0.8333
+      name: violating_precision
+    - type: recall
+      value: 0.9091
+      name: violating_recall
+    - type: f1
+      value: 0.8696
+      name: violating_f1
+---
+
+# Rukun Ready AI (Qwen2.5-32B v1)
+
+Rukun Ready AI is a Malaysia-aligned structured validation model built on `Qwen/Qwen2.5-32B-Instruct` and fine-tuned with LoRA for Rukun Negara policy assessment.
+
+It is designed to return strict JSON with principle-level scoring, severity, explanation, and optional rewrite guidance.
+
+## Model Summary
+
+- Base model: `Qwen/Qwen2.5-32B-Instruct`
+- Fine-tuning method: LoRA (instruction tuning)
+- Primary objective: structured policy validation aligned to Rukun Negara principles
+- Output format: strict JSON contract (machine-readable)
+- Languages: Bahasa Malaysia, English, Mandarin, Tamil, and code-switched input
+
+## Rukun Negara Principles Covered
+
+1. Belief in God (`belief_in_god`)
+2. Loyalty to King and Country (`loyalty_to_king_country`)
+3. Upholding the Constitution (`constitutional_compliance`)
+4. Rule of Law (`rule_of_law`)
+5. Good Behaviour and Morality (`good_behaviour_morality`)
+
+## Training Data
+
+v1 dataset used for fine-tuning:
+
+- Train: `66,516`
+- Validation: `1,353`
+- Total: `67,869`
+
+Files:
+
+- `DATASETS/rukun-teacher/v1/train_v1.jsonl`
+- `DATASETS/rukun-teacher/v1/val_v1.jsonl`
+
+Data format:
+
+- JSONL conversational records with `messages` (`system`, `user`, `assistant`)
+- Assistant targets are strict JSON responses following the schema contract
+
+Label/variant coverage (v1):
+
+- Severity variants in train:
+  - `compliant_0`: 18,674 (28.07%)
+  - `minor_1_3`: 3,511 (5.28%)
+  - `moderate_4_6`: 19,103 (28.72%)
+  - `violating_7_10`: 25,228 (37.93%)
+- Severity variants in val:
+  - `compliant_0`: 381 (28.16%)
+  - `minor_1_3`: 72 (5.32%)
+  - `moderate_4_6`: 387 (28.60%)
+  - `violating_7_10`: 513 (37.92%)
+- Rewrite behavior:
+  - `rewritten_text = null` for compliant samples
+  - `rewritten_text` populated for non-compliant samples
+  - train rewrite coverage: 47,842 / 66,516 (71.93%)
+  - val rewrite coverage: 972 / 1,353 (71.84%)
+
+## Training Procedure
+
+Reference configuration and script:
+
+- Config: `TRAINING/config_v1_b200_2gpu.yaml`
+- Trainer: `TRAINING/hf_train_v1.py`
+
+Key settings:
+
+- Max sequence length: `2048`
+- Epochs: `1`
+- Learning rate: `2e-5`
+- Scheduler: cosine
+- Precision: BF16
+- LoRA:
+  - `r=32`
+  - `alpha=64`
+  - `dropout=0.05`
+  - target modules: `q_proj`, `k_proj`, `v_proj`, `o_proj`, `gate_proj`, `up_proj`, `down_proj`
+
+Loss behavior:
+
+- Completion-only masking (loss on assistant tokens only)
+- Goal: maximize output schema stability and policy consistency
+
+Approximate trainable adaptation parameters (LoRA):
+
+- `~268M` trainable params (`~0.84%` relative to 32B base)
+
+## Evaluation Snapshot
+
+Internal labeled benchmark (`REPORT/benchmark_data.json`, n=50):
+
+- Accuracy: `88.0%`
+- Violating precision: `83.3%`
+- Violating recall: `90.9%`
+- Violating F1: `86.96%`
+
+Confusion matrix:
+
+- Expected violating -> predicted violating: `20`
+- Expected violating -> predicted compliant: `2`
+- Expected compliant -> predicted violating: `4`
+- Expected compliant -> predicted compliant: `24`
+
+## Intended Use
+
+Use this model when you need:
+
+- structured, machine-readable policy checks
+- principle-level scoring against Rukun Negara
+- multilingual moderation support for Malaysia-centric contexts
+- rewrite guidance for non-compliant text
+
+## Out-of-Scope Use
+
+Not intended for:
+
+- legal adjudication or final legal decisions
+- replacing human moderation in high-stakes enforcement without review
+- generalized truth verification or factual QA
+- medical, legal, or financial decision support
+
+## Limitations
+
+- Performance is strongest for the target policy schema and may degrade outside this format.
+- Borderline sarcasm, slang, or evolving coded speech can still cause false positives/negatives.
+- Scores are model outputs, not legal determinations.
+- Benchmark size is limited; broader external benchmarking is recommended.
+
+## Safety and Bias Notes
+
+This model is value-aligned to Malaysian national principles and can reflect the biases and policy assumptions embedded in training data design.
+
+Recommended controls:
+
+- log and audit all production decisions
+- keep human review for high-severity outcomes
+- evaluate by language/domain slices before broad rollout
+
+## Output Contract (Schema)
+
+The model is expected to return valid JSON with these keys:
+
+- `principles`
+  - `belief_in_god` -> `{status, score}`
+  - `loyalty_to_king_country` -> `{status, score}`
+  - `constitutional_compliance` -> `{status, score}`
+  - `rule_of_law` -> `{status, score}`
+  - `good_behaviour_morality` -> `{status, score}`
+- `overall` -> `{severity_score, severity_band}`
+- `explanation`
+- `rewritten_text`
+- `violationCount`
+- `severityScore`
+- `isProblematic`
+
+Derived rules used in training targets:
+
+- `overall.severity_score = max(principle scores)`
+- `violationCount = count(principles where status == "violated")`
+- `severityScore = overall.severity_score`
+- `isProblematic = (violationCount > 0) OR (severityScore > 2)`
+
+## Sample Input / Output
+
+### Example A (Compliant)
+
+Input:
+
+```json
+{
+  "messages": [
+    {
+      "role": "system",
+      "content": "You are an AI ethics validator for Malaysia's Rukun Negara principles..."
+    },
+    {
+      "role": "user",
+      "content": "Saya setuju kita bincang isu ini dengan hormat dan ikut undang-undang."
+    }
+  ]
+}
+```
+
+Output:
+
+```json
+{
+  "principles": {
+    "belief_in_god": {"status": "compliant", "score": 0},
+    "loyalty_to_king_country": {"status": "compliant", "score": 0},
+    "constitutional_compliance": {"status": "compliant", "score": 0},
+    "rule_of_law": {"status": "compliant", "score": 0},
+    "good_behaviour_morality": {"status": "compliant", "score": 0}
+  },
+  "overall": {"severity_score": 0, "severity_band": "compliant"},
+  "explanation": "Teks ini menggalakkan perbincangan berhemah dan pematuhan undang-undang, jadi ia mematuhi semua prinsip.",
+  "rewritten_text": null,
+  "violationCount": 0,
+  "severityScore": 0,
+  "isProblematic": false
+}
+```
+
+### Example B (Violating)
+
+Input:
+
+```json
+{
+  "messages": [
+    {
+      "role": "system",
+      "content": "You are an AI ethics validator for Malaysia's Rukun Negara principles..."
+    },
+    {
+      "role": "user",
+      "content": "Laws here are useless, we should ignore them."
+    }
+  ]
+}
+```
+
+Output:
+
+```json
+{
+  "principles": {
+    "belief_in_god": {"status": "compliant", "score": 0},
+    "loyalty_to_king_country": {"status": "violated", "score": 4},
+    "constitutional_compliance": {"status": "violated", "score": 7},
+    "rule_of_law": {"status": "violated", "score": 8},
+    "good_behaviour_morality": {"status": "violated", "score": 6}
+  },
+  "overall": {"severity_score": 8, "severity_band": "violating"},
+  "explanation": "The text explicitly encourages rejecting national law and constitutional order, which is a clear violation.",
+  "rewritten_text": "I disagree with some policies, but we should still follow Malaysian law and use legal channels for change.",
+  "violationCount": 4,
+  "severityScore": 8,
+  "isProblematic": true
+}
+```
+
+## Usage (Transformers)
+
+```python
+from transformers import AutoTokenizer, AutoModelForCausalLM
+import torch
+
+model_id = "Entermind/qwen25-32b-rukun-v1-merged"
+
+tokenizer = AutoTokenizer.from_pretrained(model_id)
+model = AutoModelForCausalLM.from_pretrained(
+    model_id,
+    torch_dtype=torch.bfloat16,
+    device_map="auto"
+)
+
+system_prompt = "You are an AI ethics validator for Malaysia's Rukun Negara principles..."
+user_text = "Your input text here"
+
+messages = [
+    {"role": "system", "content": system_prompt},
+    {"role": "user", "content": user_text},
+]
+
+text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+inputs = tokenizer(text, return_tensors="pt").to(model.device)
+
+with torch.no_grad():
+    output = model.generate(
+        **inputs,
+        max_new_tokens=512,
+        temperature=0.0,
+        top_p=1.0,
+        do_sample=False,
+    )
+
+print(tokenizer.decode(output[0], skip_special_tokens=True))
+```
+
+## Usage (vLLM/OpenAI-compatible)
+
+For deterministic structured outputs in vLLM, use:
+
+- `temperature=0`
+- `top_p=1`
+- bounded `max_tokens` (typically `256-512`)
+- stable, identical system prompt for better prefix-cache hit rates
+
+If model generation defaults are being auto-applied, launch vLLM with:
+
+- `--generation-config vllm`
+
+## License and Terms
+
+This release is provided as open weights. Ensure compliance with:
+
+1. Base model license (`Qwen2.5-32B-Instruct`)
+2. Repository-level terms for this model
+3. Applicable local laws and platform policy requirements
+
+## Contact
+
+- Project site: `https://rukunnegara.ai`
+- Organization: Entermind
+
+## Citation
+
+If you use this model, cite this repository and include the version tag used in your experiments.