Upload 466 files

a72d1cf verified 8 days ago

11.3 kB

---
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).

	---
	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).