bookstore-tool-calling-assistant

📚 Akıllı Kitapçı Tool-Calling Asistanı

Bu proje; bir açık kaynak dil modelinin tanımlı araçları kullanarak gerçek bir SQLite veritabanından kitap bilgisi okuduğu, sipariş oluşturduğu, stok düşürdüğü ve sipariş durumunu sorguladığı uçtan uca bir tool-calling asistanıdır.

Proje, Tool-Calling Destekli Asistan Geliştirme ödevi kapsamında hazırlanmıştır.

🎯 Senaryo

Kullanıcı doğal Türkçe ifadelerle kitapçı asistanına soru sorabilir:

• “Dune kitabının fiyatı ve stok durumu nedir?”
• “Bilim kurgu kitaplarını göster.”
• “Dune kitabından Yusuf Şimşek adına 1 adet sipariş oluştur.”
• “2 numaralı siparişim ne durumda?”
• “George Orwell kitaplarından stokta olanları listele.”

Model; fiyat, stok, kitap kimliği ve sipariş durumunu kendi bilgisinden üretmez. Gereken bilgiyi ilgili tool üzerinden SQLite veritabanından alır.

🧠 Kullanılan Teknolojiler

Model ağırlıkları uygulamaya indirilmez. Model, Hugging Face Inference Providers üzerinden çağrılır.

🏗️ Sistem Mimarisi

Kullanıcı mesajı
       │
       ▼
Qwen3-8B dil modeli
       │
       ├── Tool gerekmiyorsa → Doğrudan cevap
       │
       └── Tool gerekiyorsa
                │
                ▼
          JSON tool-call
                │
                ▼
        Python tool yönlendiricisi
                │
                ▼
           SQLite veritabanı
                │
                ▼
           Gerçek tool sonucu
                │
                ▼
        Sonuç tekrar dil modeline
                │
                ▼
      Kullanıcıya nihai Türkçe cevap

Sipariş oluşturma örneği:

search_books
      ↓
Gerçek book_id ve stok bilgisi
      ↓
create_order
      ↓
Sipariş kaydı + stok güncellemesi
      ↓
Nihai asistan cevabı

🧰 Tool Tanımları

1. search_books

Kitapları başlık, yazar veya kategoriye göre SQLite veritabanında arar.

Örnek tool-call:

{
  "name": "search_books",
  "arguments": {
    "query": "Dune",
    "in_stock_only": true
  }
}

2. create_order

Gerçek bir kitap kimliğiyle sipariş oluşturur ve kitabın stoğunu sipariş miktarı kadar azaltır.

Örnek tool-call:

{
  "name": "create_order",
  "arguments": {
    "book_id": 5,
    "quantity": 1,
    "customer_name": "Yusuf Şimşek"
  }
}

3. get_order_status

Sipariş numarasına göre sipariş bilgisini ve durumunu getirir.

Örnek tool-call:

{
  "name": "get_order_status",
  "arguments": {
    "order_id": 2
  }
}

🗄️ Veritabanı Yapısı

books tablosu

Başlangıçta farklı kategorilerden 40 örnek kitap eklenir.

orders tablosu

Sipariş oluşturma ve stok düşürme işlemleri aynı transaction içinde gerçekleştirilir. İşlemlerden biri başarısız olursa yapılan değişiklikler geri alınır.

🛡️ Halüsinasyon Engelleme

Modelin veritabanında olmayan bilgileri gerçekmiş gibi sunmasını engellemek için aşağıdaki kontroller uygulanmıştır:

1. Fiyat, stok, book_id, sipariş numarası ve sipariş durumu yalnızca tool sonuçlarından alınır.
2. create_order, aynı agent turunda search_books sonucundan gelmeyen bir book_id ile çalışamaz.
3. Model tarafından tahmin edilen kitap kimlikleri reddedilir.
4. Olmayan kitaplar boş sonuçla döndürülür.
5. Yetersiz stokta sipariş oluşturulmaz ve stok değiştirilmez.
6. Eksik müşteri adı, geçersiz miktar ve hatalı sipariş numarası Python tarafında doğrulanır.
7. Aynı kullanıcı isteğinde ikinci kez sipariş oluşturulması engellenir.
8. Model doğrudan SQL sorgusu çalıştıramaz.
9. Model yalnızca izin verilen üç tool fonksiyonunu çağırabilir.
10. Tool çağrıları terminalde ve Gradio arayüzünde loglanır.

📁 Proje Yapısı

bookstore-tool-calling-assistant/
├── app.py
├── main.py
├── agent.py
├── llm_client.py
├── prompts.py
├── tools.py
├── tool_schemas.py
├── test_tools.py
├── test_tool_schemas.py
├── requirements.txt
├── pyproject.toml
├── uv.lock
├── README.md
├── .gitignore
├── assets/
│   └── tool_call_log.png
└── data/
    ├── __init__.py
    ├── database.py
    ├── seed_database.py
    ├── test_database.py
    └── data/
        └── bookstore.db

data/data/bookstore.db çalışma sırasında otomatik oluşturulur ve Git deposuna eklenmez.

⚙️ Yerel Kurulum

1. Projeyi klonlayın

git clone <GITHUB_REPO_LINKI>
cd bookstore-tool-calling-assistant

2. uv ile bağımlılıkları kurun

uv sync

Gradio projede bulunmuyorsa:

uv add gradio

Alternatif: pip

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. Hugging Face hesabına giriş yapın

hf auth login

Alternatif olarak token ortam değişkeni şeklinde tanımlanabilir:

export HF_TOKEN="hf_..."

Hugging Face tokenı kaynak koda yazılmamalıdır.

▶️ Terminal Uygulamasını Çalıştırma

uv run python main.py

Örnek kullanım:

Sen: Dune kitabının fiyatı ve stok durumu nedir?

TOOL CALL: search_books
Arguments: {"query": "Dune"}

Asistan:
Dune kitabının fiyatı 320 TL, mevcut stok miktarı 7 adettir.

🖥️ Gradio Arayüzünü Çalıştırma

uv run python app.py

Alternatif:

python app.py

🧪 Testler

Veritabanı testi

uv run python data/test_database.py

Tool fonksiyonları testi

uv run python test_tools.py

Test edilen senaryolar:

• Kitap arama
• Olmayan kitabı arama
• Sipariş oluşturma
• Stok azaltma
• Sipariş durumu sorgulama
• Yetersiz stok
• Geçersiz sipariş numarası
• Test siparişinin silinmesi ve stoğun geri yüklenmesi

Tool şemaları testi

uv run python test_tool_schemas.py

Kontrol edilen durumlar:

• Üç tool şemasının bulunması
• JSON Schema yapısının doğrulanması
• Tool ve Python fonksiyonu adlarının eşleşmesi
• Zorunlu parametrelerin kontrolü
• Normal ve strict şemaların üretilmesi

✅ Uçtan Uca Çalışan Örnek

Kullanıcı girdisi:

Dune kitabından Yusuf Şimşek adına 1 adet sipariş oluştur.

Arka planda gerçekleşen işlemler:

1. search_books({
     "query": "Dune",
     "in_stock_only": true
   })

2. Veritabanı sonucu:
   title = Dune
   book_id = 5
   price = 320 TL
   stock = 7

3. create_order({
     "book_id": 5,
     "quantity": 1,
     "customer_name": "Yusuf Şimşek"
   })

4. Sipariş sonucu:
   order_id = 2
   total_price = 320 TL
   status = Hazırlanıyor
   stock = 7 → 6

Nihai asistan cevabı:

Yusuf Şimşek adına Dune kitabından 1 adet sipariş başarıyla
oluşturuldu.

Sipariş numarası: 2
Toplam tutar: 320 TL
Sipariş durumu: Hazırlanıyor

📷 Tool-Call Log Ekran Görüntüsü

Hugging Face’e yüklemeden önce terminal veya Gradio arayüzündeki tool-call logunun ekran görüntüsü:

assets/tool_call_log.png

adıyla eklenmelidir.

☁️ Hugging Face Space Ayarları

Space ayarlarında aşağıdaki secret tanımlanmalıdır:

HF_TOKEN

İsteğe bağlı ortam değişkenleri:

HF_MODEL=Qwen/Qwen3-8B
HF_PROVIDER=auto

⚠️ Kalıcılık Notu

Hugging Face Space’in varsayılan disk alanı kalıcı değildir. Space yeniden başlatıldığında çalışma sırasında oluşturulan demo siparişleri silinebilir ve örnek SQLite veritabanı yeniden oluşturulabilir.

Bu proje bir eğitim ve canlı demo uygulamasıdır. Gerçek üretim ortamında PostgreSQL, MySQL veya yönetilen bir veritabanı servisi kullanılmalıdır.

🔐 Güvenlik

• Hugging Face tokenı kaynak kodda tutulmaz.
• Token, ortam değişkeni veya Hugging Face Space Secret olarak alınır.
• .env, .venv ve çalışma zamanı SQLite dosyaları Git’e eklenmez.
• Model doğrudan SQL sorgusu çalıştıramaz.
• Model yalnızca izin verilen tool fonksiyonlarını çağırabilir.
• Tool argümanları Python tarafında yeniden doğrulanır.

📊 Proje Durumu

📷 Uygulama Ekran Görüntüleri

Gradio Kullanıcı Arayüzü

Aşağıdaki ekran görüntüsünde kullanıcı, bilim kurgu kategorisindeki stokta bulunan kitapları listelemektedir. Model search_books fonksiyonunu çağırmış ve yanıtını SQLite veritabanından dönen gerçek sonuçlara göre oluşturmuştur.

Tool-Call Ayrıntıları

Aşağıdaki görüntüde model tarafından seçilen tool, gönderilen parametreler ve veritabanından dönen gerçek JSON sonucu görülmektedir.

👨‍💻 Geliştirici

Yusuf Şimşek

Fırat Üniversitesi
Yapay Zekâ ve Veri Mühendisliği

📄 Lisans

Bu proje eğitim amacıyla hazırlanmıştır ve MIT Lisansı altında sunulmaktadır.