KizilelmaAI

Problem

BTK Akademi Hackathon 2026'nın finans konseptinde çalıştım. Ele aldığım somut sorun şu: yüksek enflasyon ortamında bütçe yönetmek isteyen biri, harcama listesini kendi başına anlamlı kategorilere ayırmakta ve buradan uygulanabilir bir plana geçmekte zorlanıyor. Elektronik tablo tutmak veri girişi problemi çözüyor ama yorumlama problemini çözmüyor. Amacım harcama satırlarını serbest metinden alıp kategorize eden ve üzerine Türkiye bağlamında bütçe planı üretebilen bir arka uç kurmaktı.

Yaklaşım

FastAPI arka ucu dört uç sunuyor: /chat (çok turlu sohbet), /harcama-analiz (agentik kategorize + rapor), /butce-olustur (bütçe planı) ve /health. Model gemini-2.5-flash, erişim google-genai SDK'sı üzerinden. Kategorize işini serbest metne bırakmak yerine bir function declaration olarak tanımladım: kategorize_harcama aracı, kategoriyi kapalı bir enum'dan (gida, ulasim, kira_aidat, faturalar, eglence, saglik, giyim, egitim, tasarruf, diger), risk seviyesini üç kademeden seçmek ve kısa bir öneri döndürmek zorunda. Analiz akışı iki turlu: birinci çağrı tool call'ları üretiyor, kod bunları toplayıp kategori dağılımını sayıyor, ikinci çağrı bu dağılımı prompta geri koyarak markdown raporu yazdırıyor. Ön yüz React 18 + Vite; sohbet geçmişi istemciden geliyor ve build_contents ile Gemini'nin user/model rol biçimine çevriliyor, yani sunucu oturum tutmuyor.

Kararlar ve takaslar

• 01Kategorize işini serbest metin yerine Gemini function calling ile yaptım (types.FunctionDeclaration + enum'lu types.Schema), çünkü kategorilerin sabit bir kümeden gelmesini ve zorunlu alanların şemayla garanti edilmesini istedim; alternatif modelden JSON istemekti, o zaman kategori adları koşumlar arasında kayıyor ve ayrıştırma hatalarını elle yakalamak gerekiyordu.
• 02Harcama analizini iki çağrıya böldüm: önce tool call turu, sonra toplanan kategori dağılımı prompta geri verilerek rapor turu. Çünkü tek turda hem yapılandırılmış kategori çıktısı hem uzun markdown rapor istemek ikisini birden zayıflatıyordu; alternatif tek çağrıydı ve bir istek fazladan gecikme karşılığında daha temiz bir ayrım aldım.
• 03Sıcaklığı uç ve tur başına ayarladım: sohbet 0.7; harcama analizinin kategorize turu 0.3, rapor turu 0.5; bütçe 0.4. Kategorize turunda tutarlılık, rapor turunda biraz daha akıcılık istedim. Çünkü sohbet akıcılık isterken kategorize ve rapor tutarlılık istiyor; alternatif tek bir global sıcaklıktı, o da ya sohbeti kuru ya analizi savruk yapıyordu.
• 04Sistem promptunu tek bir sabitte topladım ve içine açık sınır yazdım ("kesin yatırım tavsiyesi verme, genel bilgi çerçevesinde kal", finans dışı soruyu kibarca reddet). Çünkü finans alanında model kendiliğinden tavsiye kipine kayıyor; alternatif sınırı her endpoint'in prompt'una dağıtmaktı, o zaman uçlar arasında tutarsızlaşıyordu.
• 05API anahtarı yoksa client'ı None bırakıp uçların 500 dönmesini seçtim, çünkü anahtarsız durumda sessizce sahte/boş cevap üretmesindense açıkça hata vermesi doğru; alternatif varsayılan bir sahte cevap döndürmekti, o demo sırasında gerçek cevapla karışabilirdi.

Sonuç

ÖLÇÜM YOK — bu projede hiçbir sayı iddia edemem, çünkü depoda test, değerlendirme seti ya da koşum kaydı yok. Somut çıktı şudur: dört uçlu çalışan bir FastAPI servisi (chat, harcama-analiz, butce-olustur, health), enum kısıtlı tek bir tool declaration'ı, iki turlu analiz akışı, uç başına sıcaklık ayarı ve React 18 + Vite ön yüzü. /harcama-analiz cevabı analiz metninin yanında toplam harcamayı, kategori dağılımını ve kaç agent çağrısı yapıldığını (agent_calls) döndürüyor — yani agentik davranış istemciye ölçülebilir biçimde raporlanıyor. Depodaki CLAUDE.md yarışma takvimini veriyor: teslim 19.05.2026, ön jüri 20-30.05.2026, jüri sunumu 05.06.2026. Depoda yarışma SONUCU, puan ya da derece bilgisi YOK; bu sayfa bir sonuç iddia etmiyor. Dürüst bir teknik borç notu: frontend/src altında Vite'ın vanilla-TypeScript şablonundan kalan kullanılmayan dosyalar duruyor (main.ts, counter.ts, style.css, assets/typescript.svg) — index.html yalnızca /src/main.jsx yüklüyor, yani bunlar ölü dosya.

Teknolojiler