README.md

---
title: VYS SQL Öğrenme
emoji: 🗃️
colorFrom: blue
colorTo: indigo
sdk: gradio
app_file: app.py
pinned: false
short_description: Adım adım SQL öğreten ders uygulaması
---

# 🗃️ VYS SQL Öğrenme Uygulaması

BÖTE lisans öğrencileri için, en basit `SELECT`'ten çok tablolu `JOIN` ve
alt sorgulara kadar **25 konuluk** sıralı bir SQL kursu.

Her konuda öğrenci:
1. Kavramı kısa bir anlatımla okur,
2. **Çalıştırılmış bir örnek** ve onun sonucunu görür,
3. Kendi **görevini** yazar,
4. Sınırsız deneme yapar; hata alırsa açıklama ve ipucu alır.

Her 5 konuda bir **⭐ Geriyayılım görevi** gelir: o ana kadar öğrenilen
her şeyi tek bir sorguda birleştiren kapsamlı tekrar.

## Mimari — neden bu şekilde

**Doğru/yanlış kararını dil modeli vermez.** Öğrencinin SQL'i gerçek bir
SQLite veritabanında çalışır; sonucu, referans çözümün aynı veriler
üzerindeki sonucuyla karşılaştırılır. Farklı yazılmış ama aynı sonucu
üreten çözümler de doğru sayılır.

**Dil modelinin tek işi öğretmek:** hata mesajını Türkçeleştirmek ve
cevabı söylemeden ipucu vermek. Bu ayrım önemli — model "bu sorgu doğru mu"
sorusuna güvenilir cevap vermez, ama "bu hata ne demek" sorusuna verir.

**Maliyet:** SQL çalıştırma ve görev kontrolü yereldir, ücretsizdir,
kotadan düşmez. Yalnızca `💡 İpucu İste` butonu model çağırır.

## Dosyalar

| Dosya | İşi |
|---|---|
| `app.py` | Gradio arayüzü, giriş, ipucu kotası |
| `ilerleme.py` | İlerlemenin HF Dataset'e kaydı |
| `mufredat.py` | 25 konunun anlatımı, örneği, görevi, referans çözümü |
| `veritabani.py` | Yalıtılmış SQLite kum havuzu ve tohum veri |
| `degerlendirme.py` | Deterministik görev doğrulaması |
| `kullanici_uret.py` | Öğrenci hesaplarını üretir (yerel araç, Space'e yükleme) |
| `rapor.py` | Sınıf ilerleme raporu çıkarır (yerel araç, Space'e yükleme) |

## Kurulum

### 1. Öğrenci hesapları

```bash
python kullanici_uret.py 45
```

`ogrenciler.csv` → dağıtacağın liste. Ekrana basılan satır → `APP_USERS`.

### 2. Space secret ve variable'ları

| Ad | Tür | Değer |
|---|---|---|
| `HF_TOKEN` | Secret | Fine-grained token — aşağıdaki iki izin |
| `APP_USERS` | Secret | `ogr01:abc123,ogr02:def456,...` |
| `ILERLEME_DEPOSU` | Variable | `SSSAssist/vys-sql-ilerleme` |
| `MODEL` | Variable | `openai/gpt-oss-120b` |
| `IPUCU_GUNLUK_LIMIT` | Variable | `40` |
| `IPUCU_TOPLAM_LIMIT` | Variable | `2000` |

Zorunlu olanlar `HF_TOKEN` ve `APP_USERS`. `ILERLEME_DEPOSU` boş bırakılırsa
uygulama çalışır ama ilerleme kaydedilmez (öğrenciye uyarı gösterilir).

### Token izinleri

Fine-grained token, org olarak `SSSAssist/*` seçili, **iki** kutu işaretli:

- **Inference** → `Make calls to Inference Providers on behalf of selected orgs`
- **Repositories** → `Write access to contents/settings of repos in selected orgs`

İkincisi ilerleme kaydı için gerekli. Yalnızca ipucu isteniyorsa birincisi yeter.

### İlerleme deposu

Önce bir **private dataset** oluşturun: huggingface.co/new-dataset →
owner `SSSAssist`, ad `vys-sql-ilerleme`, görünürlük **Private**.

Her öğrenci kendi dosyasına yazar: `ilerleme/ogr01.json`. Ayrı dosya olmasının
sebebi yarış koşulu: tek ortak dosyada aynı anda çalışan öğrenciler birbirinin
kaydını ezerdi.

Kayıt iki anda yapılır: bir görev **ilk kez doğru** çözüldüğünde ve öğrenci
**konu değiştirdiğinde**. Her ipucunda yazmak gereksiz commit üretirdi.

### Sınıf raporu

```bash
export HF_TOKEN=hf_...
python rapor.py SSSAssist/vys-sql-ilerleme
```

Kim nerede, kaç deneme yapmış, kaç ipucu almış, sınıfın en çok zorlandığı
konular hangileri — hepsini ekrana basar ve `sinif_raporu.csv` üretir.

### 3. Space'e yüklenecek dosyalar

`app.py`, `mufredat.py`, `veritabani.py`, `degerlendirme.py`, `ilerleme.py`,
`requirements.txt`, `README.md`

`kullanici_uret.py` ve `rapor.py` yerel araçlardır, yüklemeyin.

### 4. Yerelde deneme

```bash
pip install -r requirements.txt
export HF_TOKEN=hf_...
export APP_USERS="test:test123"
export ILERLEME_DEPOSU=SSSAssist/vys-sql-ilerleme   # istege bagli
python app.py
```

## Veritabanı şeması

| Tablo | Sütunlar |
|---|---|
| `ogrenciler` | `id`, `ad`, `soyad`, `sinif`, `sehir`, `dogum_yili` |
| `dersler` | `id`, `ad`, `kredi`, `ogretmen` |
| `notlar` | `id`, `ogrenci_id`, `ders_id`, `puan` |

12 öğrenci, 5 ders, 30 not kaydı. Veriler bilinçli olarak Türkçe karaktersiz
yazıldı; öğrenci `WHERE sehir = 'Eskisehir'` yazarken karakter sorunu yaşamasın.

Sınır değerleri (tam 50 ve tam 60 puan) kasten eklendi: `<` ile `<=`
arasındaki farkı görev kontrolü yakalayabilsin diye.

## Konu sırası

1-9 Temel sorgulama · **10 ⭐** · 11-14 Özetleme ve gruplama · **15 ⭐** ·
16-19 Tablo oluşturma ve değiştirme · **20 ⭐** · 21-24 JOIN ve alt sorgu · **25 ⭐**

## Bilinen sınırlar

- **İlerleme dataset'e yazılıyor**, ama depo erişilemezse öğrenci uyarı görür
  ve o oturum bellekte çalışır. Sessizce sıfırlama yapılmaz.
- Dönem boyunca dataset'te yüzlerce commit birikir (öğrenci başına ~25-50).
  Bu HF için sorun değil ama depo geçmişi uzun olur.
- **İpucu kotası bellekte.** Space yeniden başlarsa sıfırlanır; asıl bütçe
  koruması `IPUCU_TOPLAM_LIMIT`'tir.
- Ücretsiz CPU donanımında 48 saat ziyaretçi olmazsa Space uyur.
- Parolalar `APP_USERS` içinde düz metindir. Sınıf içi erişim kontrolüdür,
  gerçek bir kimlik doğrulama sistemi değildir.