Blame for README.md

---
license: apache-2.0
base_model: Qwen/Qwen3.5-2B-Base
tags:
- clef
- systemone
- decision-model
- zero-token
- latent-reasoning
- turkish
- classification
datasets:
- bezir/MMLU-pro-TR
metrics:
- accuracy
model-index:
- name: KUTUP-1-Decision-2B
  results:
  - task:
      type: multiple-choice
      name: Multiple Choice Question Answering
    dataset:
      name: MMLU-Pro-TR
      type: bezir/MMLU-pro-TR
    metrics:
    - name: Accuracy
      type: accuracy
      value: 34.12
---

# 🚀 KUTUP-1-Decision-2B: Türkçe SystemOne Karar Motoru (0-Token Latent Decision)

**KUTUP-1-Decision-2B**, Cloudflare'ın öncülük ettiği **CLEF / SystemOne (Classification via Latent Evidence Fusion)** mimarisi referans alınarak, `Qwen/Qwen3.5-2B-Base` omurgası üzerinde sıfırdan inşa edilmiş ve eğitilmiş **ilk yerli Türkçe Ayrımcı Karar Motorudur.**

Geleneksel üretken LLM'lerin (Autoregressive) aksine, bu model yeni kelimeler üretmez (0-Token Inference). Girdi metnini tek bir ileri geçişte (Forward Pass) işleyerek sadece **43 milisaniyede** doğrudan yapılandırılmış kararlar, olasılık dağılımları ve kalibre edilmiş güven skorları üretir.

---

## 🏆 Benchmark Karşılaştırması: MMLU-Pro-TR (bezir/MMLU-pro-TR)

10 seçenekli (A-J), üniversite ve doktora seviyesindeki 11.842 adet zorlu Türkçe soru üzerinde yapılan genel bilgi ve akıl yürütme değerlendirmesi:

| Model | Mimari / Türü | Parametre Boyutu | MMLU-Pro-TR Doğruluk | Ortalama Gecikme |
| :--- | :--- | :---: | :---: | :---: |
| **Cloudflare CLEF-Flash** | Ayrımcı SystemOne (Global) | **9B** | **%41.88** | 79.67 ms |
| **KUTUP-1-Decision-2B (Bu Model)** | **Ayrımcı SystemOne (Türkçe)** | **2B** | **%34.12** | **43.12 ms** |
| **LiquidAI/d1-3B** | Multimodal / Autoregressive | **3B** | **%27.24** | 17.11 ms |
| **Laya-Multilingual** | mmBERT Karar Modeli | **~300M** | **%11.76** | 10.48 ms |

### 💡 Kritik Başarılar:
1. **+1 Milyar Parametre Üstünlüğü:** Kendisinden 1 milyar daha büyük parametreye sahip olan `LiquidAI/d1-3B` modeline **neredeyse 7 puan net fark** atmıştır (%34.12 vs %27.24).
2. **4.5 Kat Büyük 9B Modelin Ensesinde:**
   - **Biyoloji:** %59.52 (LiquidAI: %49.58)
   - **Psikoloji:** %49.87 (LiquidAI: %35.13)
   - **İktisat:** %46.27 (LiquidAI: %34.46)
   - **Sağlık:** %39.00 (LiquidAI: %20.25)
   - **Bilgisayar Bilimi:** %34.76 (LiquidAI: %24.18)
   - **Mühendislik:** %37.41 (9B modelin %40.21'lik skoruna yakın rekabette)

---

## 🛠️ Mimari ve Katman Tasarımı

1. **Omurga (Backbone):** `Qwen/Qwen3.5-2B-Base` (LoRA adaptörleri ile r=32, α=64).
2. **Context Memory Projeksiyonu:** 2048 boyutlu omurga uzayını 1024 boyutlu karar uzayına indirgeyen darboğaz katmanı.
3. **EvidenceRoutingBlock (Cross-Attention):** Seçeneklerin metindeki kanıtları kendi içine çekmesini sağlayan delil toplama bloğu.
4. **Joint Transformer Decoder (x4):** Seçeneklerin birbirini eleme mantığıyla yarıştığı derin karar katmanı.
5. **İkili Skorlayıcı (Prior + Gated Residual MLP):** Sözcüksel benzerlik ile derin mantıksal çelişkileri birleştiren nihai kapılı skorlama modülü.

---

## 📚 Nasıl Eğitildi?

Model 2 aşamalı disiplinli bir eğitimden geçmiştir:
- **Aşama 1 (Head Warmup):** Qwen omurgası dondurularak 100.000 örnekle sadece `JointSchemaHead` katmanları ısıtıldı.
- **Aşama 2 (Knowledge & Decision LoRA):** 38.3 milyon tokenlık "3'lü Altın Harman":
  - 35.000 adet çok alanlı kurumsal sentetik sözleşme (max 1.500 token),
  - 13.985 adet saf akademik MMLU-TR sorusu (57 disiplin),
  - 25.000 adet NLI mantıksal çelişki verisi.
  - Parametre başına düşen token oranı **1.004 token / parametre** ideal seviyesine oturtuldu. Brier Kalibrasyonu ile güven skorları hizalandı.

---

## 💻 Hızlı Kullanım (Quickstart)

Model, standart Hugging Face `transformers` kütüphanesi üzerinden doğrudan `AutoModel` ve `AutoTokenizer` ile kullanılabilir:

```python
import torch
from transformers import AutoModel, AutoTokenizer

model_id = "TurkishCodeMan/KUTUP-1-Decision-2B"

# 1. Tokenizer ve Modeli Yükle (GPU üzerinde ~6-8 GB VRAM)
tokenizer = AutoTokenizer.from_pretrained(model_id, trust_remote_code=True)
model = AutoModel.from_pretrained(
    model_id,
    trust_remote_code=True,
    device_map="cuda:0",
    torch_dtype=torch.bfloat16
)

# 2. Durum ve Karar Sorularını Tanımla
durum = "Hasta 48 yaşında erkek. Göğüs sol tarafında sıkıştırıcı ağrı ve EKG'de ST yükselmesi mevcut."
sorular = {
    "klinik_teshis": {
        "type": "choice",
        "instructions": "Bu klinik tablo için en olası acil tanı nedir?",
        "criteria": {
            "A": "Akut Miyokard Enfarktüsü (Kalp Krizi)",
            "B": "Gastroözofageal Reflü",
            "C": "Panik Atak",
            "D": "Kaburga Kas Zedelenmesi"
        }
    }
}

# 3. Tek İleri Geçişte (43 ms) Kararı Al
sonuc = model.decide(tokenizer=tokenizer, state=durum, questions=sorular)
print(sonuc["answers"]["klinik_teshis"])
# Çıktı: {'choice': 'A', 'confidence': 0.9517, 'probabilities': {'A': 0.9517, 'B': 0.0154, 'C': 0.0147, 'D': 0.0183}}
```

---

## 🔮 Gelecek Planları (Roadmap)
- **Stage 3: RLCD (Reinforcement Learning from Contrastive Decisions):** Daha geniş ve filtrelenmiş Türkçe karar senaryoları üzerinde çeldirici eleme politikasını pekiştirerek 2B boyutuyla 9B modelin genel skorunu geride bırakmak.

---

## 📜 Lisans & Atıf
Bu model açık kaynak topluluğu için Apache 2.0 lisansı altında paylaşılmıştır.
Geliştirici: **TurkishCodeMan**