pilot/README.md

Pilot çalışma: geliştirmede görülmemiş belge düzenleri

Bu klasördeki pilot, sistemi geliştirme sırasında hiç görmediği belge düzenleriyle sınar. Gerçek belgeler bulunana kadar kurgusal belgeler kullanılıyor; ancak aynı düzenek gerçek belgelerle de değiştirilmeden çalışır.

Dosya	Ne işe yarar
belge_uret.py	Kurgusal pilot belgeleri, 44 soruyu ve altın cevapları üretir (tohum 31)
belgeler/	Faaliyet raporu (PDF), KAP tarzı finansal tablolar (PDF), il istatistik bülteni (HTML)
sorular.json	Sorular ve ham veriden hesaplanan altın cevaplar
ham_degerler.json	Değer geri çağırma ölçümü için belgedeki tüm ham sayılar
pilot_calistir.py	Pilotu çalıştırır: çıkarım tanılaması ve cevap doğruluğu
kod_parmak_izi.txt	Pilot öncesi dondurulan kodun SHA-256 özetleri
sonuclar/	Dondurulmuş kodla sonuçlar: pilot_sonuclari.json ve pilot.db
sonuclar_duzeltme/	Pilotta bulunan hatalar düzeltildikten sonraki sonuçlar
kod_parmak_izi_duzeltme.txt	Düzeltilmiş kodun SHA-256 özetleri
PILOT_RAPORU.md / Tablo2SQL-TR_Pilot_Raporu.docx	Pilot raporu

Bütün kurum, il ve ilçe adları kurgusaldır ve her sayfada "KURGUSAL ÖRNEK BELGE" uyarısı vardır.

Çalıştırma

python pilot/belge_uret.py          # belgeleri ve soruları yeniden üretir
python pilot/pilot_calistir.py      # kural tabanlı arka uçla pilotu çalıştırır

Bir LLM arka ucuyla çalıştırmak için --claude, --openai MODEL ya da --ollama MODEL ekleyin.

Gerçek belgelerle kullanım

1. Belgeleri bir klasöre koyun, örneğin pilot_gercek/belgeler/.

2. Soruları bir JSON dosyasına yazın. Altın SQL gerekmez, yalnızca beklenen cevabı belgeden okuyup yazın:

   {"sorular": [
     {"id": "R01", "belge": "rapor.pdf", "soru": "2024 personel gideri gerçekleşmesi ne kadar?", "tip": "sayi", "cevap": 406187663.15},
     {"id": "R02", "belge": "rapor.pdf", "soru": "En yüksek bütçeli gider türü hangisi?", "tip": "metin", "cevap": "Sermaye Giderleri"},
     {"id": "R03", "belge": "rapor.pdf", "soru": "Gerçekleşmesi %90'ın altında kalan gider türleri hangileri?", "tip": "liste", "cevap": ["Faiz Giderleri", "Borç Verme"]},
     {"id": "R04", "belge": "rapor.pdf", "soru": "2019 yılı personel sayısı kaç?", "tip": "cevapsiz", "cevap": null}
   ]}
   

   Bir sayının işareti önemli değilse (ör. parantezli giderlerde) soruya "isaret_serbest": true ekleyin.

3. Pilotu çalıştırın:

   python pilot/pilot_calistir.py --belgeler pilot_gercek/belgeler --sorular pilot_gercek/sorular.json --cikti pilot_gercek/sonuclar
   

Değer geri çağırma ölçümü (--ham) isteğe bağlıdır; gerçek belgelerde ham değer listesi yoksa atlanır.

Değerlendirme kuralları

Doğruluk cevap düzeyinde ölçülür; altın SQL kullanılmaz.

• sayi: sonucun ilk satırındaki sayılardan biri |a − b| ≤ 0,01 + 10⁻³·|b| ile beklenene eşitse doğru.
• metin: ilk satırdaki metinlerden biri Türkçe katlama sonrası beklenene eşitse doğru. Tarihler ISO karşılığıyla karşılaştırılır ("Ekim 2025" = "2025-10").
• liste: ilk sütundaki değer kümesi beklenen kümeye eşitse doğru.
• cevapsiz: sistem cevap üretmezse doğru.

Cevap düzeyindeki ölçüt, yanlış SQL'in tesadüfen doğru değeri döndürdüğü durumları da doğru sayabilir. Bu yüzden sonuçlar SQL'lerle birlikte incelenmelidir.