DS-48 — Veriyle Konuşan Asistan (Tool Use / Function Calling)

Modül: Generative AI ve LLM (ML-05 — Tool Use) • Süre: 2-3 saat

🎯 Proje Senaryosu

"Spreadsheet'inle sohbet et." Elinde bir ürün tablosu (DataFrame) var. Kullanıcı doğal dille soruyor: "Kaç ürün var?", "Ortalama fiyat ne?", "Kaç elektronik ürün var?"

LLM bu soruları kendi başına yanıtlamaz — uydurabilir (halüsinasyon). Bunun yerine LLM, senin yazdığın TOOL'ları (gerçek hesabı yapan fonksiyonları) çağırmaya karar verir. Sen de tool-call döngüsünü yazarsın:

1. Niyet: LLM, hangi tool'u hangi argümanla çağıracağına karar verir → {"tool": "sutun_ortalamasi", "args": {"sutun": "fiyat"}}
2. Çalıştır: Sen o tool'u gerçek veriyle çalıştırırsın (deterministik, doğru sonuç).
3. Sonuç: Sonucu döndürürsün.

Modern LLM uygulamalarının (agent'lar, "X ile sohbet et" ürünleri) çekirdeği tam olarak budur: LLM karar verir, kod hesaplar.

🧩 Kullandığın Araçlar

• ✅ Tool (function) yazımı — DataFrame üzerinde saf, deterministik fonksiyonlar
• ✅ OpenAI function-calling JSON şeması — tool'ları modele tanıtma (tool_tanimlari)
• ✅ Dispatch / router — gelen tool adını doğru fonksiyona yönlendirme (arac_calistir)
• ✅ Tool-call döngüsü — niyet → çalıştır → sonuç (cevapla)
• ✅ pandas ile veri sorgulama

🔌 LLM Nasıl Çalışıyor? (önemli)

Fonksiyonların LLM'i parametre olarak alır (llm). Bu bir fonksiyondur: soru (str) alır, tool-çağırma niyetini JSON string olarak döndürür → {"tool": "...", "args": {...}}.

• Gerçek kullanımda kendi OpenAI/Anthropic çağrını verirsin (aşağıya bak) → model gerçekten hangi tool'u çağıracağına karar verir.
• Testlerde deterministik bir sahte LLM verilir → API key gerekmez, puanlama her zaman aynı.

Aynı kod, sadece verdiğin llm değişir. (Bu, profesyonel dependency injection desenidir — test edilebilir LLM kodu yazmanın yolu.)

📦 Kurulum

git clone <your-fork-url>
cd ds-48-veriyle-konusan-asistan

python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt

python watch.py                 # otomatik test (dosya değişince)
# veya
pytest tests/test_question.py -v

🔑 Kaizu Bağlantısı — kaizu_config.py

USER_ID = 0      # ← Kaizu profilinden alıp buraya yaz
PROJECT_ID = 728 # ← Bu projeye ait, DOKUNMA

📝 Görevler (tasks/task_manager.py)

#	Fonksiyon	Ne yapar
0	load_data()	Gömülü ürün tablosu (DataFrame: ad/kategori/fiyat/stok)
1a	satir_sayisi(df)	TOOL: satır (ürün) sayısı
1b	sutun_ortalamasi(df, sutun)	TOOL: sayısal sütun ortalaması
1c	kategoriye_gore_say(df, kategori)	TOOL: kategorideki ürün sayısı
2	tool_tanimlari()	3 tool'un OpenAI JSON-schema tanımı
3	arac_calistir(ad, argumanlar, df)	Dispatch: adı doğru tool'a yönlendir
4	cevapla(soru, df, llm)	Tool-call döngüsü: niyet → çalıştır → sonuç
5	pipeline(sorular, df, llm)	Çoklu soruyu sırayla cevapla

🚀 Gerçek LLM ile Çalıştır (deneyim — puanlanmaz ama YAP!)

🔑 Önce API key (sadece gerçek-LLM denemesi için — testlerde GEREKMEZ)

1. Anahtar al: platform.openai.com → Billing'e küçük bakiye yükle → API keys → Create. (Anthropic için console.anthropic.com.)
2. .env oluştur ve anahtarını oraya koy — bu dosya .gitignore'da, commit edilmez:

   cp .env.example .env
   # .env içeriği:  OPENAI_API_KEY=sk-...

3. Kur: pip install openai python-dotenv
4. ⚠️ Anahtarı ASLA koda, kaizu_config.py'ye ya da git'e yazma — yalnızca .env'e. (Spending limit koymayı da unutma.)

Testler sahte LLM ile geçer; ama asıl öğrenme, kodu gerçek bir modelle çalıştırmaktır. Gerçek function-calling'de modele tools parametresi verilir; model bir tool_call döndürür (hangi tool, hangi argüman). Aşağıda kısaltılmış bir örnek — çekirdek fikir aynı: LLM tool çağırma niyeti üretir, senin döngün çalıştırır.

from dotenv import load_dotenv
load_dotenv()                       # .env'den OPENAI_API_KEY okunur
import json
from openai import OpenAI
from tasks.task_manager import load_data, tool_tanimlari, cevapla

client = OpenAI()

def gercek_llm(soru):
    r = client.chat.completions.create(
        model="gpt-5.4-mini",                       # ucuz, ideal
        messages=[{"role": "user", "content": soru}],
        tools=tool_tanimlari(),                     # tool'ları modele tanıt
        tool_choice="required",                     # mutlaka bir tool seçsin
        temperature=0,
    )
    call = r.choices[0].message.tool_calls[0]       # modelin seçtiği tool
    # cevapla() bizim {"tool","args"} formatımızı bekliyor → uyarlayalım:
    return json.dumps({"tool": call.function.name,
                       "args": json.loads(call.function.arguments)})

df = load_data()
print(cevapla("Ortalama fiyat ne kadar?", df, gercek_llm))   # gerçek tool-call

💡 Aynı cevapla fonksiyonu hem testte (sahte llm) hem burada (gerçek llm) çalışır — işte dependency injection'ın gücü. Gerçek tool-calling akışında ek olarak tool sonucunu tekrar modele verip doğal dilde cevap ürettirebilirsin; bu projede odak, tool'ları + döngüyü senin yazman.