riskval 0.0.1__tar.gz

riskval-0.0.1/.gitignore

@@ -0,0 +1,10 @@
+
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage

riskval-0.0.1/CLAUDE.md

@@ -0,0 +1,215 @@
+# riskval — Agent Çalışma Talimatı
+
+Bu dosya, `riskval` paketi üzerinde çalışan agent'ın sözleşmesidir. Kod yazmadan önce tamamını oku.
+
+---
+
+## 1. Misyon
+
+Python'da **bakımlı, test edilmiş, düzenleyici doğrulama bataryası** yok. Bankaların model
+risk yönetimi (MRM) ekipleri bu testleri her yıl Excel/SAS'ta yeniden yazıyor. `mlfinlab`
+boşluğun bir kısmını dolduruyordu, kapalı kaynağa geçti. `riskval` bu vakumu dolduruyor.
+
+Kapsam: **kredi riski PD kalibrasyon testleri + piyasa riski VaR/ES backtest'leri + Basel IRB
+sermaye hesabı.** Bunların hepsi bir arada, doğrulanmış ve dokümante edilmiş.
+
+Paket aynı zamanda bir araştırma makalesinin (P1) altyapısı: sentetik veriyle eğitilen kredi
+modellerinin düzenleyici testlerden geçip geçmediğini ölçecek.
+
+---
+
+## 2. Pazarlık konusu olmayan kurallar
+
+Bunları ihlal eden bir PR kabul edilmez.
+
+1. **Her istatistiksel test, yayımlanmış bir referans değere karşı unit test edilecek.**
+   Finansal bir pakette sayılara güven *tek* satın alma gerekçesidir. Referans yoksa
+   fonksiyonu yazma — önce referansı bul. Referans kaynakları için §5.
+2. **Tescilli veriye bağımlılık yok.** Bloomberg/Refinitiv gereken kod bu pakete girmez.
+   Testler sentetik veya kamuya açık veriyle çalışır.
+3. **Girdi `numpy` array veya `pandas` Series/DataFrame'dir.** Kendi veri sınıfını dayatma.
+4. **Bağımlılık minimum:** numpy, scipy, pandas. Başka bir şey eklemek için gerekçe yaz.
+5. **Her fonksiyonun docstring'i literatür referansı içerir** — yazar, yıl, formülün geldiği
+   denklem. Kullanıcı "bu sayı nereden geliyor" sorusunu docstring'den cevaplayabilmeli.
+6. **Sessiz başarısızlık yok.** Geçersiz girdi (negatif n, [0,1] dışı olasılık, boş dizi)
+   açık bir `ValueError` fırlatır.
+7. **Test kapsamı %85 altına düşmez.**
+
+---
+
+## 3. Modüller ve API
+
+Hepsi `src/riskval/` altında. Sıra, yapılış sırasıdır.
+
+### 3.1 `calibration.py` — PD kalibrasyon testleri (ÖNCE BUNU YAZ)
+
+Kredi riskinde denetim otoritesinin fiilen uyguladığı testler. Rating sınıfı (grade) bazlı.
+
+```python
+binomial_test(n: int, defaults: int, pd_hat: float, alpha: float = 0.05,
+              alternative: str = "greater") -> TestResult
+    # Tek rating sınıfı için. H0: gerçekleşen temerrüt oranı <= tahmin edilen PD.
+    # Tam binom testi (normal yaklaşım DEĞİL — küçük sınıflarda yanlış sonuç verir).
+
+jeffreys_test(n: int, defaults: int, pd_hat: float, alpha: float = 0.05) -> TestResult
+    # Bayesçi alternatif. Beta(defaults + 0.5, n - defaults + 0.5) posterior'undan p-değeri.
+    # ECB/EBA IRB doğrulama talimatlarında önerilen test — bunu doğru yap, ayırt edici özellik.
+
+hosmer_lemeshow(y_true, y_prob, n_bins: int = 10, strategy: str = "quantile") -> TestResult
+    # C-istatistiği. chi2, serbestlik derecesi = n_bins - 2.
+    # strategy: "quantile" (eşit sayıda gözlem) veya "uniform" (eşit genişlik).
+
+spiegelhalter_z(y_true, y_prob) -> TestResult
+    # Brier skorunun ayrıştırılmasına dayalı Z testi. Spiegelhalter (1986).
+
+calibration_curve_table(y_true, y_prob, n_bins=10) -> pd.DataFrame
+    # Sınıf başına: n, gözlenen temerrüt, tahmin edilen PD, güven aralığı.
+```
+
+`TestResult`: `dataclass` — `statistic`, `pvalue`, `reject`, `alpha`, `test_name`, `detail: dict`.
+`__repr__` insan tarafından okunabilir tek satır versin.
+
+**Toplu arayüz:**
+```python
+grade_level_report(df: pd.DataFrame, grade_col, n_col, defaults_col, pd_col,
+                   alpha=0.05) -> pd.DataFrame
+    # Her rating sınıfı için binom + Jeffreys, ve toplam red oranı.
+    # P1'in ana çıktısı bu — "düzenleyici red oranı" buradan geliyor.
+```
+
+### 3.2 `backtest.py` — VaR / ES backtest'leri
+
+```python
+kupiec_pof(violations, n_obs: int, alpha: float) -> TestResult
+    # Koşulsuz kapsama LR testi. Kupiec (1995). chi2, df=1.
+
+christoffersen_independence(violations) -> TestResult
+    # Bağımsızlık LR testi. Christoffersen (1998). chi2, df=1.
+
+christoffersen_cc(violations, alpha: float) -> TestResult
+    # Koşullu kapsama = POF + bağımsızlık. chi2, df=2.
+
+basel_traffic_light(n_violations: int, n_obs: int = 250, alpha: float = 0.01) -> str
+    # "green" | "yellow" | "red" + sermaye çarpanı eklentisi.
+    # n_obs=250, alpha=0.01 için BCBS eşikleri: yeşil 0-4, sarı 5-9, kırmızı 10+.
+    # Bu tam sayıları unit test'e sabitle.
+
+acerbi_szekely(returns, var_forecast, es_forecast, alpha) -> TestResult
+    # ES backtest, Z1 ve Z2 istatistikleri. Acerbi & Szekely (2014).
+```
+
+### 3.3 `discrimination.py` — Ayrıştırma gücü
+
+```python
+auc_with_ci(y_true, y_prob, n_boot=1000, seed=None) -> tuple[float, float, float]
+gini(y_true, y_prob) -> float          # = 2*AUC - 1, bankacılığın kullandığı ölçüt
+ks_statistic(y_true, y_prob) -> float
+somers_d(y_true, y_prob) -> float
+```
+
+### 3.4 `capital.py` — Basel IRB sermaye
+
+```python
+irb_risk_weight(pd: float, lgd: float, maturity: float = 2.5,
+                asset_class: str = "corporate", size_adj_turnover: float | None = None) -> float
+    # BCBS Basel çerçevesi / CRR Md. 153-154 formülü.
+    # Korelasyon R, vade ayarı b, sermaye gereksinimi K, RW = K * 12.5.
+    # asset_class: "corporate" | "retail_mortgage" | "retail_qrre" | "retail_other"
+    # Her varlık sınıfının kendi R formülü var — hepsini ayrı ayrı test et.
+
+rwa(pd, lgd, ead, **kwargs) -> float
+
+rwa_deviation(pd_true, pd_hat, lgd, ead, **kwargs) -> dict
+    # Miskalibrasyonun sermaye etkisi: mutlak ve yüzde sapma.
+    # P1'in punchline'ı: "%X sermaye hatası".
+```
+
+### 3.5 `report.py` — Üst seviye arayüz
+
+```python
+validate(y_true, y_prob, grades=None, alpha=0.05) -> ValidationReport
+```
+Tüm bataryayı çalıştırır. `ValidationReport`: `.to_frame()`, `.summary()` (metin),
+`.rejected` (red edilen testlerin listesi).
+
+**README'nin ilk ekranında bu beş satır çalışır olmalı:**
+```python
+from riskval import validate
+report = validate(y_true, y_prob)
+print(report.summary())
+```
+
+---
+
+## 4. Yapılış sırası
+
+| Adım | İş | Bitmiş sayılma koşulu |
+|---|---|---|
+| 1 | `TestResult` dataclass + `_validation.py` (girdi kontrolleri) | Testleri geçiyor |
+| 2 | `calibration.py` — binom, Jeffreys | Referans değerlere karşı test yeşil |
+| 3 | `calibration.py` — Hosmer-Lemeshow, Spiegelhalter Z | R karşılaştırması yeşil |
+| 4 | `calibration.grade_level_report` | Örnek veri üzerinde çalışıyor |
+| 5 | `discrimination.py` | sklearn ile AUC karşılaştırması yeşil |
+| 6 | `capital.py` — IRB formülü | BCBS örnek değerlerine karşı test yeşil |
+| 7 | `backtest.py` — Kupiec, Christoffersen, trafik ışığı | Referans değerler yeşil |
+| 8 | `report.py` + README quickstart | 5 satır çalışıyor |
+| 9 | CI (GitHub Actions), ruff, kapsam raporu | Yeşil |
+| 10 | v0.1.0 → PyPI | `pip install riskval` çalışıyor |
+
+`acerbi_szekely` v0.2'ye ertelenebilir. Diğerleri v0.1 kapsamındadır.
+
+---
+
+## 5. Referans değerleri nereden bulacaksın
+
+Bu, işin en önemli kısmı. Sıra:
+
+1. **Orijinal makaledeki sayısal örnek.** Kupiec (1995) ve Christoffersen (1998) makalelerinde
+   çalışılmış örnekler var. Spiegelhalter (1986) aynı şekilde.
+2. **BCBS / EBA / ECB dokümanları.** Basel trafik ışığı eşik tablosu ve IRB formülü resmî
+   metinlerde açık. IRB formülünü BCBS'in kendi örnek hesaplamasıyla doğrula.
+3. **R paketleriyle çapraz doğrulama.** En pratik yol:
+   - `rugarch::VaRTest` → Kupiec + Christoffersen
+   - `ResourceSelection::hoslem.test` → Hosmer-Lemeshow
+   - `pROC::roc` → AUC ve CI
+   R'ı bir kez çalıştır, çıkan sayıları test dosyasına **sabit olarak göm** ve yorumda
+   hangi komuttan geldiğini yaz. R'ı bağımlılık yapma.
+4. **Analitik özel durumlar.** Örn. binom testinde `defaults=0` veya `defaults=n` gibi
+   uç durumlar elle hesaplanabilir.
+
+Her test dosyasının başında referansın kaynağı yorumda belirtilecek.
+
+---
+
+## 6. Yapma
+
+- Yeni özellik eklemeden önce mevcut modülleri bitirme. Kapsam genişletme en büyük risk.
+- Makine öğrenmesi modeli eğitme. Bu paket **değerlendirir**, model kurmaz.
+- Grafik çizme (matplotlib) v0.1'e girmez. Veri döndür, çizimi kullanıcıya bırak.
+- Veri indirme kodu yazma. Paket veri kaynağı değil.
+- Performans optimizasyonu yapma. Doğruluk > hız. Vektörize et, Cython'a girme.
+- Paket adını değiştirme. `riskval` PyPI'da rezerve edildi.
+
+---
+
+## 7. Bağlam
+
+- Sahibi: PhD öğrencisi, sentetik veri değerlendirme metodolojisi üzerine çalışıyor.
+  Yayımlanmış işi: IEEE Access 2026 (LLM tabular synthesizers config sensitivity).
+- Bu paket, `~/Desktop/PhD/finance-studies/` altındaki P1 makalesinin altyapısı.
+  Makale sorusu: *sentetik veriyle eğitilen kredi modelleri AUC'de iyi görünürken
+  düzenleyici testlerden kalıyor mu?*
+- İlk gerçek kullanım: `~/Desktop/PhD/tstr-calibration-audits/results/reliability.csv`
+  (kutu bazlı `mean_pred`, `frac_pos`, `weight`) üzerinde `grade_level_report` çalıştırmak.
+  API'yi tasarlarken bu girdiyi aklında tut.
+- Hedef: JOSS (Journal of Open Source Software) makalesi. JOSS'un kabul kriterleri
+  (dokümantasyon, testler, katkı rehberi, açık lisans) baştan sağlanacak şekilde çalış.
+
+## 8. Geliştirme
+
+```bash
+source ../.venv/bin/activate     # üst dizindeki ortam
+pip install -e ".[dev]"
+pytest --cov=riskval --cov-report=term-missing
+ruff check src tests
+```

riskval-0.0.1/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.5
+Name: riskval
+Version: 0.0.1
+Summary: Regulatory validation battery for credit-risk and market-risk models: PD calibration tests, VaR/ES backtests, Basel IRB capital.
+Project-URL: Homepage, https://github.com/muratsahin/riskval
+Project-URL: Issues, https://github.com/muratsahin/riskval/issues
+Author: Murat Sahin
+License-Expression: MIT
+Keywords: backtesting,basel,calibration,credit-risk,model-risk,model-validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# riskval
+
+Regulatory validation battery for credit- and market-risk models.
+
+**Status: skeleton. Name reserved on PyPI.**

riskval-0.0.1/README.md

@@ -0,0 +1,5 @@
+# riskval
+
+Regulatory validation battery for credit- and market-risk models.
+
+**Status: skeleton. Name reserved on PyPI.**

riskval-0.0.1/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "riskval"
+version = "0.0.1"
+description = "Regulatory validation battery for credit-risk and market-risk models: PD calibration tests, VaR/ES backtests, Basel IRB capital."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Murat Sahin" }]
+keywords = ["credit-risk", "model-validation", "calibration", "basel", "backtesting", "model-risk"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Intended Audience :: Financial and Insurance Industry",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = ["numpy>=1.24", "scipy>=1.10", "pandas>=2.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-cov", "ruff", "build", "twine"]
+
+[project.urls]
+Homepage = "https://github.com/muratsahin/riskval"
+Issues = "https://github.com/muratsahin/riskval/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/riskval"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

riskval-0.0.1/src/riskval/__init__.py

@@ -0,0 +1,3 @@
+"""riskval — regulatory validation battery for risk models."""
+
+__version__ = "0.0.1"