Blame for README.md

---
license: cc-by-4.0
language:
- tr
- en
pretty_name: "TR-TabloSQL: Türkçe belge tablolarında Text-to-SQL"
task_categories:
- table-question-answering
- question-answering
tags:
- text-to-sql
- turkish
- table-extraction
- pdf
- benchmark
- llm-evaluation
size_categories:
- 1K<n<10K
configs:
- config_name: tr_tablosql
  data_files: veri/tr_tablosql.jsonl
- config_name: pilot
  data_files: veri/pilot.jsonl
- config_name: stres
  data_files: veri/stres.jsonl
- config_name: agir
  data_files: veri/agir.jsonl
- config_name: gercek
  data_files: veri/gercek.jsonl
- config_name: sonuclar
  data_files: veri/sonuclar.jsonl
---

# Tablo2SQL-TR ve TR-TabloSQL

**Türkçe belgelerdeki tabloları sorgulanabilir bir bilgi tabanına dönüştüren uçtan uca sistem, test kümeleri ve LLM deney sonuçları.**

Tablo2SQL-TR, PDF, HTML, CSV ve XLSX belgelerdeki tabloları çıkarır. Birleşik hücreleri ve çok satırlı başlıkları çözer. Türkçe sayı, tarih ve birim yazımlarını normalleştirir (`1.234,56` → 1234.56, `(1.200)` → −1200, `Ocak 2024` → `2024-01`). Tabloları meta veriyle birlikte SQLite'a aktarır. Türkçe soruları kendini düzelten bir ajanla SQL'e çevirir. Cevap tablolarda yoksa uydurmak yerine bunu açıkça söyler.

Bu depoda üç şey bir arada:

1. **Uygulama:** kaynak kod, web arayüzü ve tek tıkla başlatıcılar.
2. **Test kümeleri:** 5 küme, 1.406 soru.
3. **Deney sonuçları:** kural tabanlı üretici ve 6 LLM için soru düzeyinde 5.012 kayıt.

*English summary at the end.*

![Soru sor sekmesi](docs/ekran/03_soru_sor.png)

## Öne çıkan sonuçlar

Doğruluk, cevap düzeyinde ölçüldü. Her sistem aynı sorulara, aynı veritabanlarında cevap verdi.

| Küme | Kural tabanlı | Claude Opus 5.5 | GPT-6.1-sol | Qwen2.5-Coder-32B (yerel) |
|---|---|---|---|---|
| Stres (33 belge, 307 soru) | %42,7 | **%89,9** | %76,9¹ | %62,5 |
| Ağır, hızlı alt küme (200 soru) | %14,5 | **%90,0** | %83,0 | %63,5 |
| Gerçek belge pilotu (18 belge, 189 soru) | %19,6 | %59,8 | **%62,4** | %28,6 |
| Sessiz yanlış, gerçek belgeler | %40,7 | **%2,6** | %5,3 | %9,5 |

¹ Bu çalıştırmada 34 soruda API hata döndürdü. Bu sorular dışarıda tutulursa sonuç %85,0.

- **Yerel sayı biçimi bir ön koşul.** TR-TabloSQL'de Türkçe normalizasyonla kural tabanlı üretici %92,9'a ulaşıyor. İngilizce yerel ayar varsayıldığında, kusursuz altın SQL sorgularının bile yalnızca %28,4'ü doğru sonuç veriyor ve hiçbir hata mesajı çıkmıyor.
- **Güçlü LLM'lerle darboğaz tablo çıkarımına kayıyor.** Gerçek belgelerde değeri veritabanına doğru okunamamış 32 sorudan her model yalnızca ikisini çözebildi. Bu sorular dışarıda tutulunca bulut modelleri %70,7–73,9'a çıkıyor.
- **Denetim zinciri sessiz hataları yakalıyor.** 159 bozuk sorguyla yapılan hata enjeksiyonunda hataların %92,5'i yakalandı ve hiç yanlış alarm üretilmedi.

## Ekran görüntüleri

| | |
|---|---|
| ![Belgeler](docs/ekran/01_belgeler.png) **Belgeler:** tablo çıkarma; birleşik hücreler mavi, Türkçe sayılar çözümlenmiş | ![Bilgi tabanı](docs/ekran/02_bilgi_tabani.png) **Bilgi tabanı:** aktarılan tablolar, meta veri, SQL konsolu ve dışa aktarma |
| ![Soru sor](docs/ekran/10_soru_red.png) **Soru sor:** cevap ve SQL; tablolarda olmayan bir varlık için gerekçeli red | ![Hata kataloğu](docs/ekran/04_hata_katalogu.png) **Hata kataloğu:** Türkçeye özgü hata tipleri, örnekler ve önlemler |
| ![Değerlendirme](docs/ekran/05_degerlendirme.png) **Değerlendirme:** modelleri test kümelerinde karşılaştırma, seviyelere göre doğruluk | ![Otomasyon](docs/ekran/06_otomasyon.png) **Otomasyon:** testleri ve modelleri seçip arka planda çalıştırma |
| ![Raporlar](docs/ekran/07_raporlar.png) **Raporlar:** geçmiş çalıştırmalar; raporları tek tek ya da ZIP olarak indirme | ![Genel rapor](docs/ekran/08_genel_rapor.png) **Genel rapor (HTML/PDF, TR/EN):** aydınlık/karanlık tema |
| ![Test raporu](docs/ekran/09_test_raporu.png) **Test raporu:** soru tipi, zorluk ve soru ailesine göre kırılım | |

## Hızlı başlangıç

```bash
# Windows: baslat.bat (çift tık) · macOS: baslat.command · Linux:
bash baslat.sh
```

Başlatıcı şunları kendisi yapar:

- Gerekirse Python'u kurar.
- Bir sanal ortam oluşturur ve paketleri yükler.
- Tarayıcıda `http://localhost:8501` adresini açar.

Uygulama LLM olmadan, kural tabanlı üreticiyle çalışır. Claude, OpenAI ya da yerel Ollama modelleri **Bağlantılar** düğmesinden eklenir.

Docker ile çalıştırmak için:

```bash
docker compose up -d        # durdurmak için: docker compose stop
```

Elle kurulum, tüm seçenekler ve deneyleri yeniden üretme adımları için [KURULUM.md](KURULUM.md) dosyasına bakın. Ekran görüntülü kullanım kılavuzları için: [Türkçe](docs/KULLANIM_KILAVUZU.md) · [English](docs/USER_GUIDE.md).

> **Güvenlik:** API anahtarları `ayarlar/tablo2sql-ayarlar.json` dosyasına düz metin olarak yazılır. Bu dosya pakette yoktur. Kendi kopyanızı paylaşmayın ve depoya yüklemeyin.

## Test kümeleri

| Küme | Belge | Soru | İçerik | Konum |
|---|---|---|---|---|
| **TR-TabloSQL** | 6 sentetik (4 PDF, 2 HTML), 7 tablo | 99 (64 geliştirme / 35 test) | Altın SQL; Spider/BIRD tiplerinden uyarlama; 11 cevapsız soru | `benchmark/`, `data/` |
| **Pilot** | 3 | 44 | Ana kümeden bilerek farklı düzenler | `pilot/` |
| **Stres** | 33 (11 tür × 3) | 307 (39 cevapsız) | Izgara, yalnız yatay çizgi, çizgisiz PDF ve HTML | `stres_kumesi/` |
| **Ağır** | 52, tek veritabanında | 767 (200'lük hızlı alt küme) | L1–L5 seviyeleri; %20'si İngilizce, Türkçe karaktersiz ya da yazım hatalı | `agir_kume/` |
| **Gerçek belge pilotu** | 7 kurumdan 18 gerçek PDF | 189 (19 cevapsız) | Bağımsız yazılmış ve denetlenmiş sorular | `gercek_pilot/` |

Sentetik belgeler tohumlanmış rastgele sayılarla üretilir. Gerçek kurum verisi içermezler, ama Türk kamu belgelerinin düzenini ve yazım kurallarını taklit ederler. Belgeleri yeniden üreten betikler her klasördedir.

**Gerçek belgeler bu pakette yoktur,** çünkü belgelerin hakları ilgili kurumlara aittir. Belgeler kurumların internet sitelerinden indirilmeli:

- Kaynakların listesi [`gercek_pilot/README.md`](gercek_pilot/README.md) dosyasında.
- İndirilen dosyaların doğru sürüm olduğu SHA-256 özetleriyle denetlenebilir. Komut `gercek_pilot` klasöründen çalıştırılır: `sha256sum -c belgeler.sha256`.

Kod deneylerden önce donduruldu. Dosyaların SHA-256 özetleri `kod_parmak_izi.txt` dosyalarında; çalıştırma betikleri bu özetleri kontrol eder.

### Hugging Face veri görüntüleyicisi (`veri/`)

Soru kümeleri ve sonuçlar, veri görüntüleyicide açılabilsin diye düz JSONL olarak da verildi:

```python
from datasets import load_dataset
gercek = load_dataset("<kullanıcı>/tr-tablosql", "gercek", split="train")
sonuc  = load_dataset("<kullanıcı>/tr-tablosql", "sonuclar", split="train")
```

| Yapılandırma | Satır | Alanlar |
|---|---|---|
| `tr_tablosql` | 99 | `id, bolum, soru, altin_sql, cevaplanabilir, zorluk, kategoriler, kanit, tablolar` |
| `pilot`, `stres`, `agir`, `gercek` | 44 / 307 / 767 / 189 | `id, belge, soru, tip, cevap_json, aile, zorluk` ve kümeye özgü alanlar (`seviye`, `dil`, `cizim`, `sayfa`, `tablo` …) |
| `sonuclar` | 5.012 | `kume, model, calistirma, id, dogru, durum, bulunan, beklenen_json, sql` |

Cevaplar farklı tiplerde olabilir (sayı, metin ya da liste). Bu yüzden JSON metni olarak saklandılar: `json.loads(r["cevap_json"])`.

## Deney sonuçları (`sonuclar_llm/`)

| Klasör | İçerik |
|---|---|
| `20261026-021813/` | 26.10.2026 çalıştırması: her test için rastgele seçilen üst kademe model. TR-TabloSQL'de GPT-5.2, pilotta Claude Opus 5.5, stresde GPT-6.1-sol, ağır hızlı alt kümede Claude Opus 4.5, ağır tam kümede GPT-5. |
| `20261027-043315/` | 27.10.2026 çalıştırması: stres, ağır hızlı alt küme ve gerçek belge kümelerinin her biri üç modelle. 4 sa 51 dk sürdü. |
| `kural_tabanli/` | Kural tabanlı üreticinin aynı kümelerdeki sonuçları. |
| `analiz.py`, `llm_analiz.json`, `gercek_kirilim.json` | Güven aralıkları, McNemar testleri ve gerçek belgelerde belge türüne göre kırılım. |

Her test klasöründe soru başına SQL, cevap ve hakem kararı (`sonuclar.json`, `ozet_normal.json`) ile Türkçe ve İngilizce HTML/PDF raporlar bulunur.

Bulut modelleri sağlayıcı API'leriyle çalıştırıldı. API'ler sıcaklık parametresini kabul etmediği için sağlayıcının varsayılan ayarı kullanıldı; bu nedenle sonuçlar soru düzeyinde küçük farklarla değişebilir. Yerel model Ollama ile, sıcaklık 0'da çalıştırıldı.

## Klasör yapısı

```
app.py, arayuz_tema.py   web arayüzü (Streamlit)
t2s/                     çıkarma, normalizasyon, ajan, denetim zinciri, LLM istemcileri
otomasyon/               arka planda çoklu test/model çalıştırma ve rapor üretimi
benchmark/, data/        TR-TabloSQL soruları, sentetik belgeler, doğru içerik dosyaları
pilot/, stres_kumesi/, agir_kume/, gercek_pilot/   diğer test kümeleri ve raporları
veri/                    Hugging Face görüntüleyicisi için JSONL dosyaları
sonuclar_llm/            LLM ve kural tabanlı deneylerin ham sonuçları
outputs/                 TR-TabloSQL, ablasyon ve hata enjeksiyonu çıktıları
scripts/, tests/         yardımcı betikler ve testler (pytest)
docs/                    kullanım kılavuzları ve ekran görüntüleri
```

## Lisans

- **Kod:** MIT.
- **Test kümeleri ve sonuçlar:** CC BY 4.0.

Ayrıntılar [LICENSE](LICENSE) dosyasında. Gerçek belgelerin hakları ilgili kurumlara aittir.

## Atıf

Makale değerlendirme sürecindedir. Atıf bilgisi yayımlandıktan sonra eklenecektir.

---

## English summary

**Tablo2SQL-TR** is an end-to-end system for question answering over tables in Turkish documents. It:

- extracts tables from PDF, HTML, CSV and XLSX files and resolves merged cells and multi-row headers;
- normalises Turkish number, date and unit notations;
- loads the tables with metadata into SQLite;
- answers Turkish or English questions with a self-correcting Text-to-SQL agent that abstains when the answer is not in the tables.

This repository contains:

- the code and web app;
- five benchmarks with 1,406 questions in total: TR-TabloSQL, pilot, stress, heavy, and an 18-document real-world pilot. Real PDFs are not redistributed; sources and SHA-256 hashes are given.
- question-level results of a rule-based generator and six LLMs (5,012 records).

The main findings:

- Locale-aware normalisation is a prerequisite. Under an English-locale assumption, even gold SQL returns correct results for only 28.4% of questions, with no error raised.
- With strong LLMs (Claude Opus 5.5 reaches 89.9–90.0% on synthetic sets and 59.8% on real documents; GPT-6.1-sol 62.4% on real documents), the bottleneck shifts from SQL generation to table extraction.

Quick start: `bash baslat.sh` (or `baslat.bat` / `baslat.command`), or `docker compose up -d`. The interface is available in English via the TR/EN switch. See [docs/USER_GUIDE.md](docs/USER_GUIDE.md).