YusufSimsek/pokemon-tool-calling

🎮 Pokémon Tool Calling Assistant

Google Gemma 4 + PokéAPI + Tool / Function Calling + Gradio + Hugging Face Spaces

Bu proje, bir Büyük Dil Modelinin (LLM) yalnızca kendi eğitim bilgisini kullanmak yerine, ihtiyaç duyduğu anda dış bir veri kaynağına bağlanan araçları (Tools / Functions) çağırmasını göstermek amacıyla geliştirilmiştir.

Kullanıcı Pokémon hakkında doğal dilde bir soru sorar. Google Gemma 4 12B IT modeli soruyu analiz eder, hangi aracın gerekli olduğuna karar verir, ilgili araç PokéAPI üzerinden gerçek veriyi getirir ve bu veri tekrar modele gönderilir.

Son aşamada model, elde edilen gerçek API verilerine dayanarak kullanıcıya Türkçe bir yanıt üretir.

🎯 Projenin Amacı

Bu projede temel olarak aşağıdaki yapı uygulanmıştır:

Kullanıcı Sorusu
       ↓
Google Gemma 4 12B IT
       ↓
Hangi Tool gerekli?
       ↓
Tool / Function Call
       ↓
PokéAPI
       ↓
Gerçek API Verisi
       ↓
Tool Result
       ↓
Gemma 4
       ↓
Gerekirse yeni Tool Call
       ↓
Nihai Türkçe Yanıt

Projenin temel amacı, bir LLM'in:

• —Kullanıcı sorgusunu anlaması
• —Kullanabileceği araçları tanıması
• —Doğru aracı seçmesi
• —Araca doğru parametreleri göndermesi
• —Public API üzerinden gerçek veri alması
• —Tool sonucunu tekrar değerlendirmesi
• —Gerekirse ikinci veya üçüncü bir araç çağrısı yapması
• —Son olarak gerçek verilere dayalı cevap üretmesi

süreçlerini tek bir uygulama içerisinde göstermektir.

🧠 Kullanılan Yapay Zekâ Modeli

Projede kullanılan model:

google/gemma-4-12B-it

Model, Google tarafından geliştirilen Gemma 4 ailesinin instruction-tuned 12B sürümüdür.

Gemma 4 ailesi yapılandırılmış Function Calling / Tool Calling kullanımını desteklediği için bu proje için tercih edilmiştir.

Model Hugging Face üzerinde:

AutoProcessor
AutoModelForMultimodalLM

kullanılarak yüklenmektedir.

Örnek:

MODEL_ID = "google/gemma-4-12B-it"

Model çağrısı Hugging Face Space içerisinde gerçekleştirilmektedir.

⚡ Hugging Face ZeroGPU

Gemma 4 12B modeli doğrudan uygulama içerisinde çalıştırıldığı için GPU gerekmektedir.

Bu nedenle proje:

Hugging Face ZeroGPU

altyapısını kullanmaktadır.

Gerçek model inference işlemi:

@spaces.GPU

dekoratörü ile işaretlenmiş fonksiyon içerisinde gerçekleştirilmektedir.

Örneğin:

@spaces.GPU(duration=90)
def generate_gemma_message(messages):
    ...

ZeroGPU ücretsiz bir GPU havuzu kullandığı için yoğun zamanlarda kullanıcı:

Waiting for a GPU to become available

mesajını görebilir.

GPU tahsis edildiğinde:

Successfully acquired a GPU

mesajı görüntülenir ve model inference işlemine başlar.

🌐 Kullanılan Public API

Projede Public API olarak:

PokéAPI

kullanılmıştır.

PokéAPI, Pokémon evreniyle ilgili yapılandırılmış veriler sağlayan ücretsiz bir REST API'dir.

Projede temel olarak iki API kaynağından yararlanılmaktadır.

Pokémon Endpoint

Bir Pokémon'un temel bilgilerini almak için:

/api/v2/pokemon/{pokemon_name}

endpoint'i kullanılmaktadır.

Örneğin:

pokemon/pikachu

çağrısı ile Pikachu hakkında aşağıdaki bilgiler elde edilebilir:

• —Pokédex ID
• —Pokémon adı
• —Tür / Types
• —Boy
• —Kilo
• —Yetenekler
• —HP
• —Attack
• —Defense
• —Special Attack
• —Special Defense
• —Speed

Type Endpoint

Pokémon türleri arasındaki saldırı ve savunma ilişkilerini almak için:

/api/v2/type/{type_name}

endpoint'i kullanılmaktadır.

Örneğin:

type/electric

ile Electric türünün:

• —Hangi türlere karşı güçlü olduğu
• —Hangi türlere karşı zayıf olduğu
• —Hangi türlere karşı dirençli olduğu
• —Hangi türlere az etkili olduğu
• —Hangi türlerden hasar almadığı
• —Hangi türlere hasar veremediği

öğrenilebilir.

🔧 Kullanılabilir Tool'lar

Modelin kullanabileceği iki temel araç bulunmaktadır.

1️⃣ get_pokemon(name)

Bu araç bir Pokémon'un gerçek verilerini PokéAPI üzerinden getirir.

Parametre

name

Pokémon'un İngilizce adıdır.

Örnek:

pikachu
charizard
bulbasaur
squirtle
blastoise

Örnek Tool Call

get_pokemon(name="pikachu")

Örnek Sonuç

{
  "id": 25,
  "name": "pikachu",
  "types": [
    "electric"
  ],
  "height_m": 0.4,
  "weight_kg": 6.0,
  "abilities": [
    "static",
    "lightning-rod"
  ],
  "stats": {
    "hp": 35,
    "attack": 55,
    "defense": 40,
    "special-attack": 50,
    "special-defense": 50,
    "speed": 90
  }
}

Bu sonuç doğrudan kullanıcıya verilmek zorunda değildir.

Önce tekrar Gemma 4 modeline gönderilir ve model kullanıcının sorusuna göre gerekli alanları yorumlar.

2️⃣ get_type_info(type_name)

Bu araç bir Pokémon türünün saldırı ve savunma ilişkilerini getirir.

Parametre

type_name

Örneğin:

electric
fire
water
grass
flying
poison
ground
rock

Örnek Tool Call

get_type_info(type_name="electric")

Dönen Veri

Araç temel olarak şu alanları üretir:

{
  "type": "electric",
  "strong_against": [],
  "weak_against": [],
  "resistant_to": [],
  "not_very_effective_against": [],
  "immune_to": [],
  "ineffective_against": []
}

Alanların anlamları:

📋 Tool / Function JSON Schema

Python içerisinde bir fonksiyon tanımlamak tek başına Tool Calling için yeterli değildir.

Modelin:

• —Hangi araçların bulunduğunu
• —Bu araçların ne yaptığını
• —Hangi parametreleri aldığını
• —Hangi parametrelerin zorunlu olduğunu

bilmesi gerekir.

Bu nedenle araçlar modele JSON Schema formatında tanımlanmaktadır.

get_pokemon JSON Schema

{
  "type": "function",
  "function": {
    "name": "get_pokemon",
    "description": "PokéAPI üzerinden bir Pokémon'un gerçek verilerini getirir.",
    "parameters": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Bilgileri alınacak Pokémon'un İngilizce adı."
        }
      },
      "required": [
        "name"
      ]
    }
  }
}

get_type_info JSON Schema

{
  "type": "function",
  "function": {
    "name": "get_type_info",
    "description": "Bir Pokémon türünün saldırı ve savunma ilişkilerini getirir.",
    "parameters": {
      "type": "object",
      "properties": {
        "type_name": {
          "type": "string",
          "description": "Pokémon türünün İngilizce adı."
        }
      },
      "required": [
        "type_name"
      ]
    }
  }
}

Bu Tool tanımları Gemma 4 modelinin chat template'ine gönderilmektedir.

Böylece model hangi fonksiyonları kullanabileceğini öğrenmektedir.

🔄 Tool Calling Nasıl Çalışıyor?

Örnek kullanıcı sorusu:

Pikachu'nun stat değerlerini göster.

Model bu sorunun gerçek Pokémon verisi gerektirdiğini belirler.

Ardından:

get_pokemon(name="pikachu")

Tool Call oluşturur.

Python uygulaması bu çağrıyı yakalar.

Ardından gerçek fonksiyon çalıştırılır:

result = get_pokemon(name="pikachu")

PokéAPI'den veri alınır.

Örneğin:

{
  "name": "pikachu",
  "stats": {
    "hp": 35,
    "attack": 55,
    "defense": 40,
    "special-attack": 50,
    "special-defense": 50,
    "speed": 90
  }
}

Bu veri tekrar Gemma 4 modeline gönderilir.

Model daha sonra kullanıcıya:

Pikachu'nun temel stat değerleri:

HP: 35
Attack: 55
Defense: 40
Special Attack: 50
Special Defense: 50
Speed: 90

benzeri bir nihai cevap üretir.

⚔️ Birden Fazla Pokémon Karşılaştırması

Örnek kullanıcı sorusu:

Pikachu ve Charizard'ı karşılaştır.
Hangisi daha hızlı?

Modelin tek bir Pokémon verisi alması yeterli değildir.

Bu nedenle iki farklı Tool Call oluşturması gerekir:

get_pokemon(name="pikachu")

ve:

get_pokemon(name="charizard")

Araç sonuçlarından:

Pikachu Speed = 90
Charizard Speed = 100

bilgileri elde edilir.

Model bu verileri karşılaştırarak:

Charizard daha hızlıdır.

Charizard'ın Speed değeri 100,
Pikachu'nun Speed değeri ise 90'dır.

şeklinde bir cevap oluşturabilir.

🔁 Multi-Turn Tool Calling

Projenin önemli özelliklerinden biri Multi-Turn Tool Calling desteğidir.

Bazı sorular tek bir Tool Call ile cevaplanamaz.

Örneğin:

Pikachu hangi türlere karşı güçlü
ve hangi türlere karşı zayıf?

Model ilk aşamada Pikachu'nun türünü bilmelidir.

Bu nedenle:

Turn 1

get_pokemon(name="pikachu")

çağrısı yapılır.

Tool sonucu:

type = electric

bilgisini verir.

Ancak kullanıcının sorusu henüz tamamen cevaplanmamıştır.

Bu nedenle model ikinci bir araç çağrısına karar verebilir:

Turn 2

get_type_info(type_name="electric")

Bu araç Electric türünün saldırı ve savunma ilişkilerini getirir.

Gerekli bütün bilgiler alındıktan sonra:

Turn 3

Nihai Model Yanıtı

üretilir.

Akış:

Kullanıcı
   ↓
Gemma 4
   ↓
get_pokemon("pikachu")
   ↓
PokéAPI
   ↓
electric
   ↓
Gemma 4
   ↓
get_type_info("electric")
   ↓
PokéAPI
   ↓
Tür ilişkileri
   ↓
Gemma 4
   ↓
Nihai Yanıt

Bu yapı, klasik tek seferlik API kullanımından farklı olarak modelin araç sonucuna göre yeni bir araç çağırabilmesini göstermektedir.

🔍 Tool Trace

Ödev gereksinimlerinden biri, modelin hangi araçları çağırdığının kullanıcı tarafından görülebilmesidir.

Bu nedenle uygulamada:

🔧 Tool Calling Adımları

isimli ayrı bir bölüm bulunmaktadır.

Örneğin:

============================================================
[Turn 1] 🔧 ARAÇ ÇAĞRILARI
============================================================

➡️ TOOL
get_pokemon

📥 PARAMETRELER

{
  "name": "pikachu"
}

⬅️ TOOL SONUCU

{
  "id": 25,
  "name": "pikachu",
  "types": [
    "electric"
  ],
  "stats": {
    "hp": 35,
    "attack": 55,
    "defense": 40,
    "special-attack": 50,
    "special-defense": 50,
    "speed": 90
  }
}

Bu bölüm özellikle ödevdeki:

Modelin hangi araçları çağırdığı ve adımlar açıkça gösterilmelidir.

gereksinimini karşılamak amacıyla geliştirilmiştir.

🔐 Tool Trace ve Gizli Düşünme Süreci

Tool Trace bölümünde modelin gizli düşünme süreci gösterilmez.

Gösterilen bilgiler yalnızca uygulamanın gerçekten gerçekleştirdiği:

• —Tool adı
• —Tool parametreleri
• —API sonucu
• —Tool Calling turu
• —Nihai cevap aşaması

bilgileridir.

Modelin özel reasoning / internal chain-of-thought içeriği arayüzde gösterilmemektedir.

🖥️ Gradio Arayüzü

Projenin kullanıcı arayüzü Gradio kullanılarak geliştirilmiştir.

Uygulamada iki temel sekme bulunmaktadır.

🎮 Pokémon Bilgi

Bu sekme doğrudan PokéAPI kullanımını göstermektedir.

Kullanıcı:

pikachu

gibi bir Pokémon adı girer.

Ardından:

🔎 Pokémon'u Getir

butonuna basar.

Uygulama doğrudan PokéAPI üzerinden bilgileri getirir.

Bu bölüm LLM kullanmadan API katmanının doğru çalıştığını test etmek için de kullanılmaktadır.

🤖 Gemma 4 Tool Calling

Bu sekme projenin asıl yapay zekâ bölümüdür.

Kullanıcı doğal dilde soru sorar.

Örneğin:

Pikachu ve Charizard'ı karşılaştır.
Hangisi daha hızlı?

Kullanıcının doğrudan:

get_pokemon(...)

yazmasına gerek yoktur.

Hangi aracın kullanılacağına Gemma 4 modeli karar verir.

🏗️ Proje Mimarisi

Uygulamanın genel mimarisi:

┌──────────────────────────────┐
│          Kullanıcı           │
└──────────────┬───────────────┘
               │
               ▼
┌──────────────────────────────┐
│       Gradio Arayüzü         │
└──────────────┬───────────────┘
               │
               ▼
┌──────────────────────────────┐
│   Google Gemma 4 12B IT     │
│                              │
│   Tool gerekli mi?           │
└───────┬──────────────────────┘
        │
        │ Evet
        ▼
┌──────────────────────────────┐
│      Tool JSON Schema        │
│                              │
│ get_pokemon                  │
│ get_type_info                │
└──────────────┬───────────────┘
               │
               ▼
┌──────────────────────────────┐
│      Python Functions        │
└──────────────┬───────────────┘
               │
               ▼
┌──────────────────────────────┐
│           PokéAPI            │
└──────────────┬───────────────┘
               │
               ▼
┌──────────────────────────────┐
│        Tool Result           │
└──────────────┬───────────────┘
               │
               ▼
┌──────────────────────────────┐
│     Gemma 4 tekrar çalışır   │
│                              │
│ Yeni Tool gerekli mi?        │
└──────────────┬───────────────┘
               │
               ▼
┌──────────────────────────────┐
│        Nihai Yanıt           │
└──────────────────────────────┘

📂 Proje Dosyaları

Projede temel olarak aşağıdaki dosyalar bulunmaktadır:

pokemon-tool-calling/
│
├── app.py
│
├── requirements.txt
│
├── README.md
│
├── PROJE_ACIKLAMASI.md
│
└── .gitattributes

app.py

Ana uygulama dosyasıdır.

İçerisinde:

• —Gradio arayüzü
• —Gemma 4 model yükleme
• —PokéAPI bağlantıları
• —Tool fonksiyonları
• —JSON Tool Schema
• —Tool Calling döngüsü
• —Tool Trace
• —Nihai cevap üretimi

bulunmaktadır.

requirements.txt

Uygulamanın ihtiyaç duyduğu Python kütüphanelerini içerir.

Temel bağımlılıklar:

gradio
requests
transformers
torch
torchvision
accelerate
safetensors

README.md

Hugging Face Space üzerinde görüntülenen ana Project Card dosyasıdır.

Projenin amacı, mimarisi, kullanılan model, Public API ve Tool Calling yapısı bu dosyada açıklanmaktadır.

PROJE_ACIKLAMASI.md

Projenin teknik detaylarını açıklamak için ayrıca oluşturulan dokümantasyon dosyasıdır.

🔐 Güvenlik

Hugging Face erişim anahtarı doğrudan kaynak kod içerisine yazılmamıştır.

Token:

HF_TOKEN

isimli bir Hugging Face Secret olarak saklanmaktadır.

Python tarafında:

HF_TOKEN = os.environ.get("HF_TOKEN")

şeklinde okunmaktadır.

Bu sayede token public Git repository içerisinde görünmez.

🧪 Örnek Test Senaryoları

Test 1 — Tek Pokémon

Pikachu'nun stat değerlerini göster.

Beklenen temel Tool:

get_pokemon(name="pikachu")

Test 2 — Pokémon Karşılaştırması

Pikachu ve Charizard'ı karşılaştır.
Hangisi daha hızlı?

Beklenen Tool çağrıları:

get_pokemon(name="pikachu")
get_pokemon(name="charizard")

Model iki Tool sonucundaki speed değerlerini karşılaştırmalıdır.

Test 3 — Stat Karşılaştırması

Bulbasaur ve Squirtle'ı
Attack ve Defense açısından karşılaştır.

Beklenen Tool çağrıları:

get_pokemon(name="bulbasaur")
get_pokemon(name="squirtle")

Test 4 — Multi-Turn Tool Calling

Pikachu hangi türlere karşı güçlü
ve hangi türlere karşı zayıf?

Beklenen akış:

Turn 1
get_pokemon(name="pikachu")

Turn 2
get_type_info(type_name="electric")

Turn 3
Nihai Yanıt

Test 5 — Daha Karmaşık Karşılaştırma

Charizard ve Blastoise'ı
stat değerleri ve tür avantajları açısından karşılaştır.

Bu soru birden fazla Tool Call ve birden fazla Tool Calling turu gerektirebilir.

🛠️ Kullanılan Teknolojiler

✅ Ödev Gereksinimleri

💡 Neden Pokémon Projesi?

Tool Calling projelerinde seçilen veri kaynağının farklı türde sorgulara izin vermesi önemlidir.

PokéAPI bu proje için uygundur çünkü tek bir veri kaynağı üzerinden:

• —Tek Pokémon sorgulama
• —İki Pokémon karşılaştırma
• —Stat karşılaştırma
• —Tür analizi
• —Güçlü/zayıf tür ilişkileri
• —Çok aşamalı sorgular

oluşturulabilmektedir.

Bu nedenle proje yalnızca basit bir API çağrısı değil, modelin hangi araca ne zaman ihtiyaç duyduğunu belirlemesini gösterebilmektedir.

⚠️ Bilinen Sınırlamalar

ZeroGPU Kuyruğu

Proje ücretsiz ZeroGPU altyapısını kullandığı için GPU yoğunluğuna bağlı olarak cevap süresi değişebilir.

Kullanıcı zaman zaman:

Waiting for a GPU to become available

mesajını görebilir.

Pokémon İsimleri

PokéAPI Pokémon isimlerini temel olarak İngilizce isimlerle sorgulamaktadır.

Bu nedenle:

pikachu
charizard
bulbasaur
squirtle

gibi isimler en güvenilir sonuçları verir.

API Bağlantısı

PokéAPI erişilemez durumda olursa Tool sonucu hata döndürebilir.

Uygulama bu hataları kullanıcıya güvenli şekilde göstermeye çalışır.

📌 Önemli Teknik Nokta

Bu projede API çağrısını doğrudan LLM yapmaz.

Gerçek işlem sırası:

1. Model Tool Call üretir.

2. Python uygulaması Tool Call'u yakalar.

3. Python ilgili fonksiyonu çalıştırır.

4. Fonksiyon PokéAPI'ye HTTP isteği gönderir.

5. PokéAPI JSON sonucu döndürür.

6. Python sonucu Tool Result olarak modele verir.

7. Model yeni bilgiye göre karar verir.

8. Gerekirse başka Tool çağırır.

9. İşlem tamamlandığında nihai cevap üretir.

Bu yapı Tool / Function Calling sistemlerinin temel çalışma prensibidir.

🎓 Sonuç

Bu proje ile:

LLM + Public API + JSON Schema + Tool Calling + Multi-Turn Tool Calling + Gradio + Hugging Face Spaces

teknolojileri tek bir uygulama içerisinde birleştirilmiştir.

Google Gemma 4 modeli kullanıcı sorgusunu analiz ederek ihtiyacı olan araçları belirlemektedir.

Araçlar PokéAPI üzerinden gerçek veriler çekmektedir.

API sonuçları tekrar modele verilmekte ve model bu verilere dayanarak kullanıcıya nihai cevap üretmektedir.

Uygulamadaki Tool Trace alanı sayesinde gerçekleştirilen araç çağrıları, parametreler ve API sonuçları kullanıcı tarafından görülebilmektedir.

Bu sayede yalnızca sonuç üreten bir chatbot yerine, dış veri kaynaklarıyla etkileşim kurabilen Tool Calling tabanlı bir yapay zekâ sistemi oluşturulmuştur.

🎮 Örnek Soru

Pikachu ve Charizard'ı karşılaştır.
Hangisi daha hızlı ve tür avantajları nelerdir?

Bu soru ile sistemin:

Gemma 4
   ↓
get_pokemon
   ↓
get_pokemon
   ↓
gerekirse get_type_info
   ↓
PokéAPI
   ↓
Gemma 4
   ↓
Nihai Yanıt

akışı test edilebilir.

Model: google/gemma-4-12B-it Public API: PokéAPI Interface: Gradio Deployment: Hugging Face Spaces GPU: ZeroGPU Method: Tool / Function Calling