README.md

metadata

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ı

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

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

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.