nursimakgul/library-tool-calling

1---2title: Kütüphane Asistanı (Tool-Calling)3emoji: 📚4colorFrom: indigo5colorTo: blue6sdk: gradio7sdk_version: 5.9.18app_file: app.py9pinned: false10---11 12# 📚 Kütüphane Asistanı — Tool-Calling Destekli13 14Kullanıcının doğal dille yaptığı isteklere göre bir dil modelinin **gerçek bir15veritabanına** (SQLite) ve **internete** (Wikipedia / Google Books) erişerek işlem yaptığı bir16tool-calling (function-calling) sistemidir. Asistan; kitap arar, öneri yapar, ödünç17verme/iade işlemlerini gerçekleştirir ve arka planda çağırdığı araçları adım adım gösterir.18 19## Canlı Demo20 21🔗 **Hugging Face Space:** _(https://huggingface.co/spaces/nursimakgul/library-tool-calling)_22 23## Senaryo24 25Bir kütüphane görevlisi asistanı. Okuyucular:26- Kitap arayabilir, bir kitabın müsait olup olmadığını sorabilir.27- Türe ve tercihe (yerli/yabancı, ince/kalın) göre **öneri** alabilir.28- Kitap **ödünç alabilir** (sistem 2 hafta sonrasına teslim tarihi atar ve en geç teslim29  tarihini bildirir).30- Kitap **iade edebilir** (sistem erken/zamanında/geç durumunu kaydeder).31- Bir kitabın **konusunu** öğrenebilir (bu bilgi veritabanında tutulmaz, internetten çekilir).32 33## Model ve Mimari34 35Kod modüler olarak ayrılmıştır:36 37| Dosya | Görev |38|-------|-------|39| `db.py` | SQLite veritabanı: kitap envanteri, ödünç/iade kayıtları (okuma + yazma) |40| `tools.py` | 6 tool fonksiyonu + JSON şemaları (modelin çağıracağı fonksiyonlar) |41| `router.py` | **Groq LLM** ile tool-calling (birincil) + kural tabanlı yedek katman |42| `app.py` | Gradio arayüzü, tool-call döngüsü, adım adım gösterim |43 44### Model ve tool-calling45 46- **Birincil:** [Groq](https://groq.com) üzerinden `llama-3.3-70b-versatile` modeli, gerçek47  function-calling ile. Model kullanıcının niyetini anlayıp doğru tool'u ve parametreleri seçer.48- **Yedek:** LLM kotası dolar ya da servis erişilemezse, sistem otomatik olarak hafif bir49  **kural tabanlı router**'a düşer. Böylece demo her koşulda ayakta kalır (graceful degradation).50 51### Tool'lar52 53| Tool | Tür | Açıklama |54|------|-----|----------|55| `kitap_ara` | DB okuma | Başlık/yazara göre arar, durumu döner |56| `kitap_oner` | DB okuma | Tür + filtrelere göre öneri getirir |57| `kitap_odunc_al` | DB yazma | Ödünç verir, 2 hafta teslim tarihi atar |58| `kitap_iade_et` | DB yazma | İade alır, erken/geç durumunu kaydeder |59| `odunc_durumu` | DB okuma | Kitabın müsaitliğini/teslim tarihini bildirir |60| `kitap_konusu` | Web | Kitabın konusunu internetten çeker (önce Wikipedia, olmazsa Google Books) |61 62### Halüsinasyon engelleme63 64Tüm yanıtlar tool'lardan dönen gerçek veriye dayanır. Veritabanında olmayan bir kitap65sorulduğunda sistem "bulunamadı" yanıtı verir; model kendi genel bilgisinden var olmayan66bir kitabı öneremez ya da uyduramaz. Kitap konusu gibi uzun bilgiler veritabanında67tutulmadığı için internetten (önce Wikipedia, olmazsa Google Books) çekilir.68 69## Yerelde Çalıştırma70 71```bash72pip install -r requirements.txt73export GROQ_API_KEY="gsk_..."   # https://console.groq.com adresinden ücretsiz alınır74python app.py75```76 77`GROQ_API_KEY` verilmezse sistem otomatik olarak kural tabanlı yedek katmanla çalışır.78Hugging Face Spaces'te `GROQ_API_KEY`, Space ayarlarından **Secret** olarak eklenmelidir.79 80---81 82## Örnek Çalışma (Tool-Call Akışı)83 84Aşağıda asistanla yapılmış gerçek bir oturum yer alır. Her yanıtın altında, arka planda85tetiklenen tool-call'lar ve bunların veritabanı/web'den döndürdüğü **gerçek veri** gösterilir.86 87### 1) Türe göre öneri (kitaptan tür çıkarımı)88 89**Kullanıcı:** ben en son dune serisini okudum ve çok beğendim buna benzer kitap önerisi yapabilir misin90 91**Asistan:** Bilim kurgu severlerin çok seveceği birkaç kitap bulundu:92- Fahrenheit 451 — Ray Bradbury (256 sayfa)93- Cesur Yeni Dünya — Aldous Huxley (288 sayfa)94- Vakıf — Isaac Asimov (296 sayfa)95- Ben, Robot — Isaac Asimov (320 sayfa)96- 1984 — George Orwell (352 sayfa)97- Marslı — Andy Weir (448 sayfa)98 99```100[Turn 1] Araç Çağrıları:101   -> kitap_oner(tur='bilim kurgu')102   <- {"bulundu": true, "adet": 6, "oneriler": [103        {"id": 23, "baslik": "Fahrenheit 451", "yazar": "Ray Bradbury", "sayfa": 256},104        {"id": 26, "baslik": "Cesur Yeni Dünya", "yazar": "Aldous Huxley", "sayfa": 288},105        {"id": 25, "baslik": "Vakıf", "yazar": "Isaac Asimov", "sayfa": 296}, ...]}106```107> Önerilen tüm kitaplar veritabanında gerçekten kayıtlıdır; model kitap uydurmaz.108 109### 2) Kitap konusu (web tool'u — Wikipedia / Google Books)110 111**Kullanıcı:** peki fahrenheit 451 in konusu nedir112 113**Asistan:** Fahrenheit 451, Ray Bradbury'nin 1953'te basılan distopik bir bilimkurgu114romanıdır. Kitapların itfaiyeciler tarafından yakıldığı, düşünmenin yasaklandığı bir115gelecekte geçer. Adı, kâğıdın yaklaşık 451 °F'de tutuşmasından gelir...116 117```118[Turn 1] Araç Çağrıları:119   -> kitap_konusu(baslik='Fahrenheit 451')120   <- {"bulundu": true, "kitap": "Fahrenheit 451", "konu": "... (Wikipedia'dan)"}121```122> Konu bilgisi veritabanında tutulmaz; internetten çekilir (önce Wikipedia, olmazsa Google Books).123 124### 3) Müsaitlik sorgusu (yalnızca bilgi verir, işlem yapmaz)125 126**Kullanıcı:** şu an boşta mı bu kitap127 128**Asistan:** Fahrenheit 451 kitabı şu an boşta.129 130```131[Turn 1] Araç Çağrıları:132   -> kitap_ara(sorgu='Fahrenheit 451')133   <- {"bulundu": true, "kitaplar": [{"id": 23, ..., "durum": "bosta"}]}134```135 136### 4) Ödünç alma (önce okuyucu adı sorulur — ad uydurulmaz)137 138**Kullanıcı:** ödünç alabilir miyim139 140**Asistan:** Kitabı kimin adına ödünç alalım?141 142**Kullanıcı:** Nur Sima Akgül143 144**Asistan:** Fahrenheit 451 kitabı Nur Sima Akgül adına 2026-08-03 tarihinde ödünç145verildi. En geç 2026-08-17 tarihinde teslim edilmesi gerekmektedir.146 147```148[Turn 1] Araç Çağrıları:149   -> kitap_odunc_al(kitap_id=23, okuyucu='Nur Sima Akgül')150   <- {"basarili": true, "kitap": "Fahrenheit 451", "okuyucu": "Nur Sima Akgül",151       "odunc_tarih": "2026-08-03", "en_gec_teslim": "2026-08-17"}152```153> Ödünç alma için okuyucu adı zorunludur; verilmezse asistan sorar, ad uydurmaz.154> Teslim tarihi otomatik olarak 2 hafta sonrasına ayarlanır.155 156### 5) Ödünç sonrası durum (veritabanı değişikliği kalıcıdır)157 158**Kullanıcı:** fahrenheit 451 kitabı boşta mı159 160**Asistan:** Fahrenheit 451 kitabı şu an ödünçte.161 162```163[Turn 1] Araç Çağrıları:164   -> kitap_ara(sorgu='Fahrenheit 451')165   <- {"bulundu": true, "kitaplar": [{"id": 23, ..., "durum": "oduncte"}]}166```167> Bir önceki adımda yapılan ödünç işlemi veritabanına yazıldığı için kitabın durumu artık168> "ödünçte" görünür. Bu, sistemin gerçek veri okuyup yazdığının kanıtıdır.169 170### Halüsinasyon engelleme171 172Veritabanında bulunmayan bir kitap sorulduğunda asistan onu "varmış gibi" sunmaz:173 174**Kullanıcı:** "İnsanın Esareti" kitabı var mı?175 176**Asistan:** Maalesef "İnsanın Esareti" kitabı kütüphanede mevcut değil.177 178```179[Turn 1] Araç Çağrıları:180   -> kitap_ara(sorgu='İnsanın Esareti')181   <- {"bulundu": false, "mesaj": "'İnsanın Esareti' ile eşleşen kitap bulunamadı."}182```183 184### Dayanıklılık (LLM limitte olduğunda yedek katman)185 186LLM servisi (Groq) hız limitine takıldığında sistem otomatik olarak kural tabanlı yedek187router'a düşer ve kesintisiz çalışmaya devam eder. Yedek katman, LLM erişilemediğinde arama,188öneri ve durum sorgulama gibi salt-okunur işlemleri karşılar; ödünç/iade gibi veritabanı 189değiştiren kritik işlemler için birincil LLM katmanı gereklidir.190 191```192[Bilgi] LLM kullanılamadı (RateLimitError), yedek router devrede.193[Yedek Router] Araç Çağrısı:194   -> kitap_oner(tur='polisiye', ...)195   <- {"bulundu": true, "oneriler": [...]}196```