README.md

---
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.

```mermaid
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

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

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

```bash
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:

```bash
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):

```json
[
  {
    "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
```