README.md

metadata

title: Tool Calling Academic Assistant
emoji: 🔬
colorFrom: blue
colorTo: indigo
sdk: gradio
app_file: app.py
pinned: false

🔬 Tool-Calling & MCP Destekli Akademik Araştırma Asistanı

Bu proje, kullanıcının akademik makale araması yapabildiği (ArXiv & Semantic Scholar API), bulduğu makaleleri kişisel SQLite veritabanındaki kütüphanesine kaydedebildiği, okuma durumunu güncelleyebildiği ve not ekleyebildiği uçtan uca çalışan bir Tool-Calling & MCP (Model Context Protocol) sistemidir.

---

📌 Proje Senaryosu ve Mimarisi

Ödev kapsamında Akademik Araştırma ve Makale Yönetim Asistanı senaryosu seçilmiştir. Sistem, dil modelinin (LLM) dış dünyaya (ArXiv API, Semantic Scholar API ve yerel SQLite Veritabanı) güvenli ve halüsinasyonsuz bir şekilde erişmesini sağlar.

graph TD
    User([Kullanıcı / Chat UI / Cursor / Claude Desktop]) <--> LLM[LLM Engine / Ollama / Groq / OpenAI]
    LLM <--> Dispatcher[Tool Call & MCP Dispatcher]
    
    subgraph Dış Kaynaklar & Veritabanı (Tool Layer)
        Dispatcher -->|1. search_arxiv_papers| ArXiv[ArXiv REST API]
        Dispatcher -->|2. search_openalex| OpenAlex[OpenAlex API]
        Dispatcher -->|3. save_paper_to_library| SQLite[(SQLite DB: academic_library.db)]
        Dispatcher -->|4. get_saved_library| SQLite
        Dispatcher -->|5. update_paper_status_or_note| SQLite
        Dispatcher -->|6. delete_paper| SQLite
        Dispatcher -->|7. clear_library| SQLite
        
    end

⚡ Öne Çıkan Özellikler:

1. Halüsinasyon Engelleme: Sistem promptu ve tool mimarisi sayesinde model veritabanında veya API'de bulunmayan uydurma bir makale/bilgi üretemez. Tüm yanıtlar gerçek tool çıktılarına dayanır.
2. Çift Mimarili Bağlantı (Tool-Calling + MCP Protocol):
   • Gradio Web UI: Hugging Face Space üzerinde canlı çalışan görsel arayüz ve canlı Tool Execution Log ekranı.
   • MCP Server (mcp_server.py): Anthropic / Linux Foundation standartlarındaki Model Context Protocol sunucusu. Claude Desktop, Cursor veya VS Code üzerinden doğrudan sunucuya bağlanabilir.
3. Sıfır Lokal Model Ağırlığı (Cloud LLM Esnekliği):
   • Bilgisayarınıza gigabaytlarca model ağırlığı indirmek zorunda kalmadan ücretsiz Groq, OpenRouter veya Remote Ollama cloud endpoint'leri ile çalışabilir.

---

🛠️ Tanımlı Fonksiyonlar (Tools)

Fonksiyon Adı	Açıklama	İşlem Türü
search_arxiv_papers	ArXiv üzerinden makale başlığı, yazar, özet ve PDF linklerini getirir.	API Read
search_openalex	OpenAlex platformundan atıf sayıları (citations) ile makale getirir.	API Read
save_paper_to_library	Seçilen makaleyi yerel SQLite veritabanına kaydeder.	DB Write
get_saved_library	Veritabanında kayıtlı makaleleri ve okuma durumunu listeler.	DB Read
update_paper_status_or_note	Kayıtlı makalelerin durumunu (unread, reading, completed) veya notunu günceller.	DB Write
delete_paper	Veritabanından belirtilen ID'ye sahip makaleyi siler.	DB Write
clear_library	Veritabanındaki tüm kayıtlı makaleleri siler.	DB Write

---

🚀 Projeyi Yerelde Çalıştırma Adımları

1. Depoyu Klonlayın ve Bağımlılıkları Yükleyin

git clone https://github.com/KULLANICI_ADI/proje.git
cd proje
pip install -r requirements.txt

2. Uygulamayı Başlatın (Web Arayüzü)

python app.py

Uygulama yerelde http://localhost:7860 adresinde çalışmaya başlayacaktır.

3. (İsteğe Bağlı) MCP Sunucusu Olarak Çalıştırma

Claude Desktop veya Cursor gibi MCP istemcilerine bağlamak için:

python mcp_server.py

---

💬 Kullanıcı Girdisi:

"Quantum computing alanındaki en son ArXiv makalelerini ara ve ilk çıkan makaleyi kütüphaneme kaydet."

---

⚙️ Arka Plan Tool-Call Log Çıktısı (JSON Trace):

[
  {
    "timestamp": "2026-08-01 11:26:44",
    "type": "TOOL_CALL_TRIGGERED",
    "name": "search_arxiv_papers",
    "input": {
      "query": "quantum computing",
      "max_results": 2
    },
    "output": {
      "status": "success",
      "count": 2,
      "papers": [
        {
          "paper_id": "arxiv_2403.02240v5",
          "title": "Quantum Computing: Vision and Challenges",
          "authors": "Sukhpal Singh Gill, Oktay Cetinkaya, Stefano Marrone",
          "published_year": "2024",
          "url": "https://arxiv.org/abs/2403.02240v5",
          "source": "ArXiv"
        }
      ]
    }
  },
  {
    "timestamp": "2026-08-01 11:26:45",
    "type": "TOOL_CALL_TRIGGERED",
    "name": "save_paper_to_library",
    "input": {
      "paper_id": "arxiv_2403.02240v5",
      "title": "Quantum Computing: Vision and Challenges",
      "authors": "Sukhpal Singh Gill, Oktay Cetinkaya, Stefano Marrone",
      "url": "https://arxiv.org/abs/2403.02240v5",
      "published_year": "2024",
      "tags": "Quantum"
    },
    "output": {
      "status": "success",
      "message": "'Quantum Computing: Vision and Challenges' başarıyla kütüphaneye kaydedildi.",
      "paper_id": "arxiv_2403.02240v5"
    }
  }
]

🤖 Modelin Nihai Yanıtı:

"Quantum computing alanında ArXiv üzerinde arama yapıldı ve 'Quantum Computing: Vision and Challenges' başlıklı makale bulundu. Makale başarıyla kişisel veritabanı kütüphanenize kaydedildi! (Makale ID: arxiv_2403.02240v5)"

---

Proje default haliyle Groq API'sine bağlı olduğu için istekleri gerçekleştirmesi uzun sürebilir veya çoklu makalelerde token yetmeyebilir. Bu nedenle her istekten sonra 5-10 saniye arası beklenmelidir.

📁 Proje Dosya Yapısı

proje/
├── app.py              # Gradio Web Arayüzü & Log İzleyici UI
├── mcp_server.py       # Anthropic Model Context Protocol (MCP) Server
├── agent.py            # LLM Tool-Calling Yönlendiricisi & Prompt Yönetimi
├── tools.py            # ArXiv API, Semantic Scholar API ve Tool Şemaları
├── database.py         # SQLite Veritabanı CRUD İşlemleri
├── config.py           # API Ayarları ve Yapılandırma
├── requirements.txt    # Gerekli Python Kütüphaneleri
└── README.md           # Proje Dokümantasyonu