InsightFlow

Verini tarayıcına bırak, doğal dille sor. Dosya cihazdan çıkmaz: sorgu motoru (DuckDB-WASM) tarayıcıda çalışır, yapay zekâya yalnızca tablonun şeması gider.

Canlı: https://insightflow-rust.vercel.app · API: https://insightflow-api-d2gf.onrender.com/docs

API, Render'ın ücretsiz planında çalışıyor ve 15 dakika boşta kalınca uyuyor. İlk açılışta 20–50 sn uyanma gecikmesi olabilir. Bu sırada arayüz "Yanıt motoru uyanıyor…" gösterir ve sunucu hazır olunca soru kutusu kendiliğinden açılır. Veri yükleme ve profil çıkarma backend'e bağlı olmadığı için hemen çalışır.

Plan ve mimari: docs/InsightFlow_Proje_Plani_v2.pdf · Performans: docs/benchmark

Durum

Faz	İçerik	Durum
1	Tarayıcıda veri çekirdeği: CSV/Parquet/Excel yükleme, motor kilidi, profil, örnek sorular, demo veri setleri	✅
2	Güvenli text-to-SQL: şema-only prompt, sqlglot doğrulama + saldırı test seti, self-healing, istek sınırı, soru-cevap akışı	✅
3	Grafik seçici (ECharts: çizgi/çubuk/dağılım/KPI) + onaylı yönetici özeti	✅
4	"Modele ne gitti?" paneli, grafik panosu (IndexedDB), durdurma, backend durumu, boş/hata durumları	✅
5	Playwright E2E, benchmark, CSP, Docker, CI, canlıya alma (Render + Vercel)	✅

Akış

Tarayıcı                                   Backend (durumsuz)                Gemini
────────                                   ──────────────────                ──────
dosya → DuckDB-WASM (kilitli)
şema {ad, tip}  + soru  ───────────────▶  POST /sql ──────────────────────▶  yapılandırılmış JSON
                                          sqlglot doğrulama ◀─────────────  {sql, açıklama, grafik}
                                          (red → nedenini modele geri besle, en fazla 3 tur)
onaylı SQL  ◀───────────────────────────
sorgu tarayıcıda koşar
  hata → değerleri maskele → POST /repair (en fazla 3 kez)
sonuç tablosu (satırlar asla sunucuya gitmez)

Performans (özet)

Ayrıntılar ve yöntem: docs/benchmark/README.md. i7-1165G7, 16 GB RAM.

	100 bin satır	1 milyon satır	5 milyon satır
Tarayıcıda 5 analitik sorgu (medyan aralığı)	9–37 ms	59–137 ms	252–510 ms
Tarayıcıda yükleme + profil	0,8 sn	3,0 sn	11,9 sn
Yerel Python: DuckDB / pandas sorgu hızı	1,4×	4,1×	4,5×
Yerel Python: tepe bellek, DuckDB'de pandas'a göre	−%48	−%37	−%29

Güvenlik

Tarayıcıda

• Dosya data tablosuna alındıktan sonra enable_external_access=false ve lock_configuration=true uygulanır. Motor, kilidi doğrulamadan veri setini açmaz. E2E testi: doğrulayıcı atlatılsa bile read_text(...) motor tarafından reddedilir.
• Aynı alan adından API + CSP (next.config.ts): tarayıcı API'ye doğrudan değil, uygulamanın kendi /api/* yolundan gider; Next bu isteği sunucu tarafında Render'a iletir. Böylece CSP connect-src 'self' olabiliyor: bir hata ya da kötü niyetli bir bağımlılık olsa bile tarayıcı uygulamanın kendi sunucusu dışında hiçbir yere istek atamaz. İlk sürümde tarayıcı *.onrender.com'a doğrudan gidiyordu ve reklam engelleyiciler bunu üçüncü taraf istek sayıp engelledi (net::ERR_BLOCKED_BY_CLIENT); vekil bu sorunu da çözdü.
• DuckDB-WASM'ın parquet/json eklentileri derleme sırasında indirilip kendi alan adından sunulur. Varsayılan davranışta çalışma anında extensions.duckdb.org'a istek atılıyordu. Bu, CSP eklenince fark edildi ve E2E testiyle kilitlendi: sayfa dış hiçbir adrese istek atmaz.
• Onarım isteğine giden DuckDB hata mesajında tırnak içi değerler ve sayılar maskelenir (src/lib/sanitize.ts).
• Onaylı örnek değerler (src/lib/data/sample-values.ts, varsayılan kapalı): kullanıcı isterse az kategorili metin sütunlarının değerleri (en fazla 12 değer, kimlik sütunları hariç, ör. islem_turu: Gelir, Gider) modele gönderilir.
  • Gönderilecek değerlerin tamamı önce gösterilir; sütun sütun seçilir.
  • Şerit ve "Modele ne gitti?" paneli paylaşılan değerleri sayar.
  • Backend değer sayısını ve uzunluğunu sınırlar.

Backend (src/insightflow/validator.py)

• Tek ifade; kök yalnızca SELECT veya UNION/INTERSECT/EXCEPT.
• Tablo izin listesi: yalnızca data ve sorgunun kendi CTE'leri. Şema niteliği, dosya yolu ve tablo fonksiyonu yasak.
• Fonksiyon izin listesi: read_csv, glob, getenv, current_setting, duckdb_* gibi fonksiyonlar SELECT içinde olsa bile reddedilir.
• LIMIT yoksa eklenir, 1000'den büyükse düşürülür.
• Ek korumalar:
  • Hata mesajları sunucuda da ayrıca temizlenir.
  • IP başına istek sınırı var.
  • Girdi boyutu ve sütun adları doğrulanır.
• tests/test_validator.py: 47 saldırı sorgusu (hepsi reddedilmeli) ve 18 gerçekçi analitik sorgu (hepsi kabul edilip gerçek DuckDB'de demo verisi üzerinde çalışmalı).

Grafikler ve yönetici özeti

• src/lib/chart-spec.ts: modelin grafik önerisi yalnızca bir ipucu. Sonucun şekli (tarih/sayı/kategori sütunları) uymuyorsa şekle uygun tür seçilir.
  • Uzun biçimli zaman serileri (ay, kategori, değer) seriye çevrilir. En fazla 4 seri çizilir, fazlası "Diğer"e toplanır.
  • Farklı büyüklükteki ölçüler tek eksende çizilmez.
• Palet: dataviz referans paletinin ilk 4 slotu, uygulamanın açık ve koyu kart yüzeylerinde validate_palette.js ile doğrulandı. Yeşil ve çivit arayüzde "cihazda kalan / modele giden" anlamına ayrıldığı için grafiklerde kullanılmaz. Her grafikte tablo görünümü var.
• Yönetici özeti, veri sözleşmesinin tek istisnası:
  • Kullanıcı onayı ve gidecek tablonun önizlemesi olmadan istek atılmaz.
  • En fazla 20 satır × 8 sütun gönderilir.
  • Sunucu, sonucu üreten SQL'in toplulaştırılmış olduğunu yeniden doğrular (summary.py). data'yı okuyan her SELECT GROUP BY veya toplama fonksiyonu içermeli; pencere fonksiyonu ve alt sorgudaki COUNT sayılmaz.

Birden fazla dosya ve birleştirme (JOIN)

• İlk dosya data tablosu olur; birlikte seçilen ya da sonradan Dosya ekle ile eklenen dosyalar adlarından türetilen tablolar olur (Müşteri Listesi.xlsx → musteri_listesi, src/lib/data/tables.ts). En fazla 4 ek tablo var.
• İlişkiler tarayıcıda bulunur: aynı adlı, uyumlu tipli anahtar sütunlar için DuckDB'de eşleşme oranı hesaplanır (ör. data.musteri_id ↔ musteriler.musteri_id · %87 eşleşme). Modele yalnızca tablo.sütun çiftleri gider; oran ve değer gitmez.
• Kilit korunur: motor dış erişime kilitli olduğu için dosya eklemek/çıkarmak yeni bir DuckDB örneğini tüm dosyalarla yeniden kurar. Eklenen dosya okunamazsa önceki veri seti çalışmaya devam eder.
• Backend: istek şeması tables ve relationships alır. Tablo adları ^[a-z][a-z0-9_]{0,39}$, data olamaz, benzersizdir; ilişkiler yalnızca bilinen tablo ve sütunlara işaret edebilir.
  • Doğrulayıcının tablo izin listesi yalnızca bildirilen tablolara genişler.
  • Yönetici özetinin toplulaştırma kuralı her gerçek tabloya uygulanır: JOIN veya UNION ile ham satır sızdırılamaz.
• Arayüz: tablolar ve ilişkiler paneli, tabloya göre şema ve önizleme, birleştirme gerektiren öneri soruları, iki tablolu demo (Siparişler + müşteriler).
• Değerlendirme (scripts/eval_join.py): gerçek modelle 5 sorunun 5'i doğru tablo kullanımıyla ilk denemede çalıştı. Buna LEFT JOIN … IS NULL ile "müşteri kaydı olmayan siparişler" de dahil. Tek tabloyla yanıtlanabilen soruda gereksiz JOIN yapılmadı.

Veriyi keşfet

• Veriyi keşfet butonu (src/lib/explore.ts), soru sormadan hazır içgörüler üretir; model çağrısı yapmaz, sorgular tarayıcıda koşar, cümleler sonuçlardan kural tabanlı ve basit istatistikle kurulur.
• Aylık trend: en yüksek ay, ortalamadan 2 standart sapma aşağıdaki olağan dışı ay, son 3 ay değişimi.
• En büyük kategorinin payı ve ilk 3 kategorinin toplam payı.
• Evet/hayır sütununda gruplar arası oran farkı (ör. iade oranı en yüksek Giyim %13,7, genel %7,3).
• İki ölçü arasındaki korelasyon (tüm veri üzerinden corr, grafik için tekrarlanabilir örneklem).
• Veri kalitesi: birebir tekrar eden kayıtlar ve %5'ten fazla boş değer içeren sütunlar.
• İçgörü kartları panoya sabitlenebilir, PDF'e girer; Buna devam et ile içgörünün SQL'i takip sorusunun bağlamı olur. Keşif sonrası soru kutusu kendiliğinden bir içgörüye bağlanmaz.
• Üç demo veri setinde yaklaşık 1 sn.

Cevap cümlesi

• Model, sonucu görmeden SQL ve "sorgu ne yapıyor" açıklaması yazar; bu açıklama soruyu cevaplamaz. Bu yüzden her yanıtın üstünde sonuçtan tarayıcıda kurulan bir cevap cümlesi gösterilir (src/lib/answer-text.ts). Model çağrısı yoktur, cümle yalnızca sonuç tablosundaki sayılardan kurulur; neden ya da tavsiye içermez.
• Sonucun şekline göre: tek satırda değerler; sıralamada en yüksek/en düşük, toplanabilir değerlerde toplamın payı ve ilk 3'ün payı; zaman serisinde ilk→son değişim ve zirve; iki sayısal sütunda ilişki.
• Ortalama ve oran gibi değerlerde "toplamın payı" verilmez; sonuç 1.000 satır sınırında kesildiyse de verilmez (eksik toplam yanıltır).
• Model açıklaması "Nasıl hesaplandı" olarak altta kalır. Cümle panoya ve PDF rapora da girer.

Neden değişti?

• Zaman serisi yanıtlarında Neden Değişti? butonu (src/lib/why.ts), seçilen iki dönem arasındaki farkı kategorilere böler (katkı analizi). Model çağrısı yapmaz, her şey tarayıcıdaki kilitli motorda koşar.
• Yanıtın SQL'i DuckDB'nin kendi ayrıştırıcısıyla (json_serialize_sql) ağaca çevrilir. Aynı sorgu, aynı FROM/JOIN ve WHERE ile, bu kez her kategorik sütuna göre de gruplanarak yeniden kurulur (json_deserialize_sql). Regex ile SQL kurcalanmaz.
• Yalnızca toplanabilir ölçülerde çalışır (SUM, COUNT, ROUND(SUM(...))). Ortalama, oran ya da benzersiz sayımın değişimi kategorilere paylaştırılamayacağı için analiz yapılmaz ve nedeni yazılır. CTE, alt sorgu, UNION, HAVING ve DISTINCT de aynı şekilde gerekçeyle reddedilir.
• Her kırılımın toplamı orijinal sonuçla karşılaştırılır; tutmazsa yanlış bir hikâye anlatmak yerine analiz gösterilmez.
• Çıktı: değişimin en büyük kaynağı, ikinci etken, ters yönde hareket eden değer ve her kırılım için artış/düşüş çubukları. Değişim tek bir değerde yoğunlaşmıyorsa bunu söyler.
• Örnek (e-ticaret demosu, iadeler hariç ciro): Kasım → Aralık 2025'te 2,8 Mn → 2 Mn (−%29,2). Düşüşün %66 kadarı "Yeni" müşteri segmentinden. Değerler Python DuckDB ile ayrıca hesaplanarak doğrulandı.

Takip soruları

• Son yanıt varsayılan olarak bağlamdır; soru kutusunun üstündeki "Önceki soruyla bağlantılı" etiketi × ile kaldırılabilir, herhangi bir karttaki Buna devam et bağlamı o karta çevirir.
• Modele bağlam olarak yalnızca önceki soru ve SQL'i gider, en fazla 3 adım geriye (src/lib/followup.ts); sonuç satırı gitmez.
• Prompt "X bazında kır" (gruplamayı koruyup ekler), "aynısını X için yap" (gruplamayı değiştirir) ve "sadece …" (filtre ekler) ifadelerini ayırır.
• scripts/eval_followup.py: gerçek modelle 3 takip zincirinin 3'ü beklenen değişikliği uyguladı. İlk koşuda "kanal bazında kır" ayları düşürüyordu; prompt bu ayrımla düzeltildi.

Şeffaflık ve pano

• Modele ne gitti? (src/lib/outbound-log.ts): sunucuya giden her istek tek bir postJson üzerinden geçer ve gövdesi gönderildiği hâliyle kayda alınır. Üst şeritteki sayılar bu kayıttan türetilir; şeride tıklayınca gövdelerin kendisi açılır.
• Pano (src/lib/pins.ts): sabitlenen yanıt, sonuç satırlarıyla (ve varsa yönetici özetiyle) birlikte yalnızca tarayıcının IndexedDB'sinde saklanır.
• PDF rapor (src/lib/report.ts): panodaki tüm analizler ya da tek bir yanıt, tarayıcıda PDF'e dönüştürülüp indirilir; sunucuya istek atılmaz.
  • İçerik: kapak ve gizlilik notu, her analiz için soru, açıklama, vektörel grafik / KPI / tablo, yönetici özeti ve SQL.
  • Grafikler ekrandakiyle aynı ayar kodundan (chart-option.ts) sabit baskı temasıyla üretilir (ECharts SSR → SVG → svg2pdf).
  • Türkçe karakterler için IBM Plex Sans gömülür (OFL lisansı public/fonts/report/OFL.txt); metin PDF'te aranabilir.
  • Rapor kodu (jsPDF) yalnızca butona basınca yüklenir.
• Soru "Durdur" ile iptal edilebilir. Backend uyuyorsa "uyanıyor" gösterilir ve kendiliğinden yeniden denenir; bu sırada sorulan soru kuyrukta bekler ve sunucu hazır olunca kendiliğinden gönderilir. 90 sn'de yanıt gelmezse neden gösterilir.

Testler

Katman	Komut	Kapsam
Backend	uv run pytest	130 test: doğrulayıcı saldırı korpusu, ek tablolarla JOIN ve izin listesi, API ve tablo/ilişki doğrulaması, özet toplulaştırma kuralı (JOIN/UNION dahil), örnek değer ve takip geçmişi sınırları, hata temizleme, istek sınırı
Frontend birim	npm test	107 test: grafik seçici, profil, öneri soruları, tablo adı ve ilişki adayları, keşif cümleleri ve plan seçimi, örnek değer adayları, takip bağlamı zinciri, onarım döngüsü, giden istek kaydı, pano deposu (özet güncelleme dahil), backend uyanma izleyicisi, cevap cümlesi, "neden değişti?" (gerçek DuckDB sorgu ağaçlarıyla uygunluk kararları, katkı hesabı, toplam doğrulaması)
Uçtan uca	npm run test:e2e	20 senaryo, gerçek Chromium + gerçek DuckDB-WASM (backend taklit edilir): dış istek yok, API aynı alan adından, veri sızıntısı yok, iki tablolu JOIN ve dosya ekleme/çıkarma, model çağrısız keşif, takip soruları, onaylı örnek değerler, motor kilidi, onarım, özet onayı, pano kalıcılığı, PDF rapor indirme, "neden değişti?" katkı analizi, durdurma, uyuyan sunucu, mobil
Model	uv run python scripts/eval_llm.py	Gerçek Gemini ile 3 veri setinde 16 soru; SQL gerçek DuckDB'de çalıştırılır (--with-values: onaylı örnek değerlerle). Ayrıca eval_followup.py (takip) ve eval_join.py (çok tablo)

Son model değerlendirmesi (15.09.2026, gemini-3.5-flash-lite, 16 soru): 14 doğru sonuç, 1 doğru red ("yarın dolar kaç olacak"), 1 yanlış red ("aylık net kâr"), 0 çalışmayan SQL.

Yanlış red, yalnızca şema gönderme kararının bilinen bedeli: model islem_turu sütununda "Gelir/Gider" değerleri olduğunu göremiyor. Önceki koşularda aynı soruyu doğru yanıtlamıştı, yani sonuç koşudan koşuya değişebiliyor.

Onaylı örnek değerlerle (--with-values, aynı gün, aynı 16 soru): 15 doğru sonuç, 1 doğru red, 0 yanlış red. "Aylık net kâr" doğru çizgi grafiğe dönüştü; "mobil ve web" karşılaştırması tam değer adlarıyla filtrelendi. Tek koşuluk bir ölçüm; model sonuçları koşudan koşuya değişebilir.

Bir model, JSON içinde çift tırnaklı sütun adını kaçıramayıp kesik SQL döndürdü. Çözüm olarak sade adlar tırnaksız yazdırılıyor ve reddedilen turlardan sonra model zinciri kaydırılıyor. Bu hatayı yakalayan iki soru sete eklendi.

Çalıştırma

# Docker ile tek komut
GEMINI_API_KEY=... docker compose up --build      # http://localhost:3000

# veya ayrı ayrı
cd backend && uv sync && uv run uvicorn insightflow.main:app --reload   # http://localhost:8000/docs
cd frontend && npm install && npm run dev                                # http://localhost:3000

Canlıya alma

Katman	Platform	Adres	Ayarlar
Arayüz	Vercel	https://insightflow-rust.vercel.app	Kök dizin frontend, NEXT_PUBLIC_API_URL=https://insightflow-api-d2gf.onrender.com (Config)
API	Render (Blueprint, Docker)	https://insightflow-api-d2gf.onrender.com	render.yaml; GEMINI_API_KEY (gizli), CORS_ORIGINS=https://insightflow-rust.vercel.app

Dikkat edilecekler:

• NEXT_PUBLIC_API_URL (ya da tercih edilen adıyla API_UPSTREAM_URL), /api/* vekilinin hedefidir ve derleme sırasında okunur; tarayıcıya gönderilmez. Değeri değiştirince Vercel'de yeniden derleme (Redeploy) şart. Tanımsız bırakılırsa vekil http://localhost:8000'e iletir; geçersiz bir değer (ör. yer tutucu metin) derlemeyi durdurur.
• Tarayıcı API'yle aynı alan adından konuştuğu için CORS aslında kullanılmıyor; CORS_ORIGINS doğrudan erişim için yedek olarak duruyor.
• Render ücretsiz planda uyuduğunda arayüz "Yanıt motoru uyanıyor…" gösterir ve 90 sn boyunca kendiliğinden yeniden dener (src/lib/health-watch.ts).
• Yeni Vercel projelerinde Deployment Protection varsayılan olarak açık gelir; herkese açık demo için Settings → Deployment Protection'dan kapatılmalı.

Canlı doğrulama (15.09.2026): üretim sitesinde headless Chromium ile demo veri seti açıldı ve "Kategori bazında iade oranı nedir?" soruldu.

• Doğru çubuk grafik geldi; tarayıcıda sorgu 9 ms, toplam yanıt 2,4 sn sürdü.
• Onaylı yönetici özeti üretildi.
• Tarayıcı yalnızca kendi alan adı ve API ile konuştu (/health, /sql, /summary); soru isteklerinde veri değeri yoktu.
• CI (.github/workflows/ci.yml): pytest, lint, tip kontrolü, vitest, production derlemesine karşı Playwright ve iki Docker imajının derlenmesi.

Yapı

frontend/   Next.js 16 + TypeScript + Tailwind + shadcn/ui, DuckDB-WASM, ECharts
  src/lib/data/engine.ts     tarayıcı içi motor (yükle → data tablosu → kilitle)
  src/lib/ask.ts             soru → /sql → tarayıcıda çalıştır → gerekirse /repair
  src/lib/chart-spec.ts      sonuç şekli → grafik tanımı
  src/lib/outbound-log.ts    giden istek kaydı ("Modele ne gitti?")
  e2e/                       Playwright senaryoları
  scripts/benchmark.mjs      tarayıcı performans ölçümü
backend/    FastAPI (Python 3.12, uv)
  src/insightflow/validator.py   AST güvenlik doğrulaması
  src/insightflow/summary.py     yönetici özeti için toplulaştırma kuralı
  src/insightflow/llm.py         Gemini (model zinciri: kota/yoğunlukta sıradakine geçer)
  scripts/                       demo/benchmark verisi, model değerlendirmesi, pandas–DuckDB karşılaştırması
docs/       plan PDF, benchmark sonuçları