Golden Dataset — Temsil Gücü ve Fairness Yönetişimi

• Sahip: Simetri
• Son Güncelleme: 2026-04-16
• Güncelleme Tetikleyicisi: Yeni dataset sürümü, yeni slice ekseni, metrik eşiği revizyonu, NIST AI RMF / EU AI Act delegated act değişikliği, slice-by-slice raporda disparate impact bulgusu.
• Çeyreklik Review: 90 günde bir temsil tablosu, slice eşikleri ve dataset-card metadata'sı güncelliği doğrulanır.
• Durum: İskelet — şablon ve süreç tanımlı; gerçek sayılar ilk golden dataset yazıldığında (geliştirme başlangıcında) doldurulur.

---

1. Neden Bu Doküman?

testing-strategy.md §3 golden dataset metriklerini (Direction Accuracy, Hallucination, Range Compliance) ve eşiklerini tanımlar. Ama dataset'in kimi temsil ettiği — yani hangi yaş, cinsiyet, eğitim, bölge gruplarının hangi ağırlıkta örneklendiği — belgelenmediği sürece şu dört sorunun yanıtı yok:

1. NIST AI RMF MEASURE 2.3 (Test verisi temsil gücü): "Dataset hedef popülasyonu yansıtıyor mu?"
2. NIST AI RMF MAP 5.1 (Etki ölçümü / bias): "Alt gruplar aggregate metrikte kaybolmuyor mu?"
3. EU AI Act Art. 10(3) (Data Governance): "Eğitim/validasyon/test verilerinin temsil gücü, hatalar ve tamamlayıcılık açısından uygunluğu" — yazılı belge şart.
4. DPIA §2.3 (bias ile yanlış öneri riski): "Bu riski hangi kanıtla 'Düşük' / 'Orta' / 'Yüksek' olarak işaretliyorum?"

Bu doküman bu dört soruya tek kaynaktan yanıt üretir: dataset-card şablonu + slice reporting kuralı + versiyonlama süreci.

Bu doküman süreç tanımıdır; gerçek örnek/metrik sayılar dataset card instance'larında yaşar (§4). Dataset büyüdükçe bu doküman değişmez — sadece instance'lar güncellenir.

---

2. Kapsam ve Kapsam Dışı

Kapsam içi:

• services/psychometric-engine/eval/datasets/ altındaki tüm golden dataset sürümleri (benchmark, regresyon, reference)
• Dataset yapısı, demografik denge hedefleri, slice-by-slice metrik raporu formatı
• Örnek ekleme/güncelleme/silme PR kuralları, sürüm politikası

Kapsam dışı:

• Adversarial/red-team eval dataset'leri → docs/security/adversarial-eval-suite.md (SIM-176 sonrası)
• LLM prompt'ları ve scoring matematiği → psychometrics/llm-orchestration.md, psychometrics/scoring-algorithms.md
• Metrik eşikleri (Direction Accuracy > %85 vb.) → testing-strategy.md §3.2

---

3. Dataset Card Şablonu

Her dataset sürümü için bir markdown dataset-card yazılır. Şablon Model Card pattern'ine (psychometrics/model-cards/TEMPLATE.md) paraleldir.

Fiziksel yol: services/psychometric-engine/eval/datasets/<dataset-name>/card.md

# Dataset Card — <dataset-name> vX.Y.Z

* **Sürüm:** vX.Y.Z (semver; §6 kuralları)
* **Tarih:** YYYY-MM-DD
* **Sahibi:** <psikometri reviewer + ML reviewer isimleri>
* **Amaç:** <regresyon / benchmark / hot-path / cold-path>
* **Örnek sayısı:** <N>
* **Kaynak:** <gerçek kullanıcı / sentetik / hibrit — oran belirt>

## 1. Kullanım Amacı (Intended Use)
Bu dataset hangi metriklerin ölçümünde kullanılır? (§3.2 testing-strategy satırlarına atıf)

## 2. Örnek Yapısı
- `scenario_id`, `transcript`, `expected_traits[]`, `expected_label`, `slice_tags[]`
- `slice_tags` demografik ve bağlamsal eksenler içerir (§5)

## 3. Temsil Tablosu (Demografik Denge)
Tablo formatı §5'te; hedef dağılım vs. mevcut dağılım + fark (%).

## 4. Slice Eksenleri
Hangi eksenlerde slice raporu üretilir: yaş bandı, cinsiyet, eğitim, bölge, bağlam odası, senaryo karmaşıklığı.

## 5. Bilinmeyen Sınırlar (Known Limitations)
- Türkiye ağırlıklı örneklem — AB pazarı için gerilim
- Sentetik senaryoların `[PRO]` etiketine yanlılığı (varsa)
- Belirli yaş/eğitim kombinasyonu az temsil ediliyorsa burada belirt

## 6. Etik ve Hukuki Not
- Tüm gerçek örnekler `vector-privacy.md` sanitization'dan geçer (T2 seviye)
- DPIA §2.3 bias risk satırının azaltıcı önlemi: bu dataset + slice eşikleri
- EU AI Act Art. 10(3) kanıt referansı

## 7. Değişiklik Logu
- vX.Y.Z (YYYY-MM-DD): <değişiklik özeti + PR link>

---

4. İlk Instance (Boş İskelet)

services/psychometric-engine/eval/datasets/golden-v0/card.md pre-development aşamasında fiziksel olarak oluşturulmaz — services/ klasörü henüz yok. Bu doküman şablonu ve kararları sabitler; ilk dataset dosyası açılan PR'da yukarıdaki şablon kopyalanır ve bu satırdaki "v0" isimlendirmesi kullanılır.

v0 = bootstrap hedefi:

• 50-100 senaryo (testing-strategy §3.1 ile tutarlı)
• En az 3 slice eksende (yaş bandı, cinsiyet, eğitim) her grupta min. 8 örnek
• Bölge ekseni v0'da "TR-only" kabulü ile işaretlenir; v1'de AB örneklemi eklenene kadar bilinen sınır

---

5. Demografik Denge ve Temsil Hedefleri

5.1. Slice Eksenleri ve Hedef Dağılım

Her örnek slice_tags[] alanında aşağıdaki eksenlerden değer taşır. Hedef dağılımlar Türkiye çalışan popülasyonu + platformun hedef B2B/B2C segmenti karışımına göre belirlenir (TÜİK İş Gücü İstatistikleri + B2B müşteri persona ağırlığı).

Eksen	Değerler	v0 Hedef	Kaynak / Gerekçe
Yaş bandı	18-24, 25-34, 35-44, 45-54, 55+	15 / 35 / 30 / 15 / 5 (%)	TÜİK işgücü + B2B orta kariyer ağırlığı
Cinsiyet	K / E / Belirtilmemiş	45 / 50 / 5 (%)	TÜİK işgücü yaklaşık oranı + aday kendi beyanı
Eğitim	Lise, Ön lisans, Lisans, Y.Lisans/PhD	20 / 20 / 45 / 15 (%)	B2B beyaz yaka ağırlığı
Bölge	İstanbul, Ankara+İzmir, Diğer TR, AB	35 / 20 / 35 / 10 (%)	v0'da AB %0; v1'de hedef %10'a çıkar
Bağlam odası	PRO / SOCIAL / NEUTRAL	60 / 20 / 20 (%)	context-rooms-design.md ağırlıklı B2B odak
Senaryo karmaşıklığı	Basit / Orta / Karmaşık	30 / 50 / 20 (%)	Üretim dağılımı tahmini

5.2. Sapma Toleransı

Her eksende her grup için mutlak sapma %5'ten fazla ise PR'da uyarı; %10'dan fazla ise dataset-card'da "Bilinmeyen Sınır" olarak belgelenmeli (§3.5).

5.3. Kesişimsel (Intersectional) Temsil

Tek eksen (örn. cinsiyet) dengeli olabilir ama yaş × cinsiyet kesişiminde çukur kalabilir (ör. 45-54 yaş kadın = 2 örnek). v0'da pairwise kontrol şart: her iki-eksen kesişiminde min. 4 örnek. Üçlü kesişim v1 hedefidir.

---

6. Slice-by-Slice Raporlama

6.1. Aggregate'ten Slice'a

testing-strategy.md §3.2 tablosundaki her metrik (Direction Accuracy, Range Compliance, Label Accuracy, Hallucination Rate, Confidence Calibration) slice başına ayrıca hesaplanır. Aggregate geçse de herhangi bir slice'ta eşik altı → CI uyarı (§7.2).

6.2. Rapor Formatı (JSON)

Eval çıktısı eval/results/<tarih>/slice-report.json olarak üretilir:

{
  "dataset_version": "golden-v0.3.0",
  "run_id": "2026-04-16T10:00Z-run-1",
  "aggregate": { "direction_accuracy": 0.87, "hallucination": 0.01 },
  "slices": [
    {
      "axis": "age_band",
      "value": "45-54",
      "n": 9,
      "metrics": { "direction_accuracy": 0.78, "hallucination": 0.02 },
      "delta_vs_aggregate": { "direction_accuracy": -0.09 }
    }
  ],
  "disparate_impact_flags": [
    { "axis": "age_band", "value": "45-54", "metric": "direction_accuracy", "reason": "delta -9pp > 5pp tolerance" }
  ]
}

6.3. Disparate Impact Eşikleri

Metrik	Slice - Aggregate farkı	Aksiyon
Direction Accuracy, Label Accuracy	≥ 5 pp düşük	Uyarı (PR comment)
Direction Accuracy, Label Accuracy	≥ 10 pp düşük	CI kırıcı
Hallucination Rate	≥ 2x aggregate	Uyarı
Hallucination Rate	≥ 5x aggregate	CI kırıcı
n (slice örnek sayısı)	< 5	Rapor "insufficient sample" — metrik atlanır

"pp" = yüzde puan. 5 pp ve 10 pp eşikleri ilk kalibrasyon; v1 sonrası gerçek dağılım görüldüğünde testing-strategy.md §4.2 ile ortak revize edilir.

---

7. Versiyonlama ve Değişiklik Süreci

7.1. Semver Kuralı

Dataset adı: golden-vMAJOR.MINOR.PATCH (örn. golden-v0.3.0).

Bump	Tetikleyici
MAJOR	Şema değişikliği (yeni zorunlu alan, slice ekseni ekleme/çıkarma), backward-incompatible
MINOR	Yeni slice grubunda örnek ekleme (ör. AB bölgesi eklendi), mevcut metrik eşikleri geçerli kalır
PATCH	Mevcut örneklerde etiket düzeltme, typo, tek örnek ekleme (temsil tablosunu %1'den fazla kaydırmıyorsa)

7.2. PR Review Kuralı

Dataset'e (şema veya içerik) dokunan her PR için:

Kontrol	Zorunlu mu?
2 reviewer: 1 psikometri uzmanı + 1 ML/mühendislik	Evet (MAJOR & MINOR için)
Dataset-card'ın §7 Değişiklik Logu güncellendi	Evet (tüm bump'lar)
Temsil tablosu (§5.1) yeniden hesaplandı ve sapma toleransı (§5.2) kontrol edildi	MINOR & MAJOR
Kesişimsel min. 4 örnek kuralı hala geçerli (§5.3)	MINOR & MAJOR
Slice-by-slice eval çalıştırıldı, disparate impact flag'i yok (§6.3)	MAJOR
CODEOWNERS: services/psychometric-engine/eval/datasets/** → psikometri takımı	Evet

PATCH için tek reviewer yeterli, ama değişiklik log'u yine zorunlu.

7.3. Silme Politikası

Örnek silmek PATCH yeterli değildir: temsil tablosunu kaydırır, MINOR bump + gerekçe (değişiklik log'unda neden silindiği — etiket hatası, PII sızıntı riski, vs.) şart.

---

8. CI Entegrasyonu

testing-strategy.md §4.1'deki llm-eval job'ına aşağıdaki adımlar eklenir (ilk implementasyon SIM-176 / SIM-177 ile birlikte):

      - name: Slice-by-slice eval
        run: python eval/run_slice_eval.py --dataset eval/datasets/golden-v0/ --output eval/results/
      - name: Disparate impact check
        run: python eval/check_disparate_impact.py --report eval/results/slice-report.json
        # Exit 1 → slice eşiği aşıldı (§6.3)
      - name: Upload slice report
        uses: actions/upload-artifact@v4
        with:
          name: slice-report
          path: eval/results/slice-report.json

CI sonucu PR'a otomatik yorum olarak yapıştırılır (aggregate + 3 en kötü slice).

---

9. Referanslar ve Çapraz Bağlantılar

Bu doküman	Referans verir	Yön
§1 (amaç)	testing-strategy.md §3 metrikleri	okur
§1, §6	security/nist-ai-rmf-mapping.md MEASURE 2.3 + MAP 5.1	✅ kısmen kanıtı
§1, §3.6	security/dpia.md §2.3 bias satırı	azaltıcı önlem kaynağı
§3 şablonu	psychometrics/model-cards/TEMPLATE.md	pattern paraleli
§5 slice eksenleri	architecture/context-rooms-design.md room_type	tutarlılık
§6 eşikleri	testing-strategy.md §4.2 PR merge kuralları	ortak kalibrasyon
§7 CODEOWNERS	ileride eklenecek .github/CODEOWNERS	ön koşul
EU AI Act Art. 10(3)	security/eu-ai-act-compliance.md §3.3	yasal çerçeve

---

10. Ne Zaman Bu Dokümana Dokunulur?

• Yeni slice ekseni (örn. engellilik durumu, dil) → §5.1 + §3 şablonu
• Disparate impact eşikleri (§6.3) kalibrasyonu değişirse → §6.3 + testing-strategy.md ortak güncelleme
• Dataset versiyonlama kuralı değişirse (§7.1) → ADR açılabilir (backward-incompatible karar)
• Dataset fiziksel yolu değişirse (services/ refactor) → §3 ve §4 yol referansları
• NIST AI RMF veya EU AI Act delegated act güncellemesi → §1 + nist-ai-rmf-mapping.md ortak

---

Son Güncelleme: 2026-04-16 — İlk sürüm; SIM-175 kapsamında dataset-card şablonu, demografik denge hedefleri, slice-by-slice raporlama kuralı ve PR review süreci tanımlandı.