Menü
Makale

Graphify Nedir, Neden Kullanmalısınız?

Erkan Doğan

• 3 dk okuma süresi

Büyük bir projeye katıldığınız ilk gün ne yaparsınız? Çoğumuz README'yi açar, klasör yapısına bakar, sonra grep ile dosyaları taramaya başlarız. Bu işlem günler sürer ve sonuç genelde eksik kalır. Graphify, kod tabanınızı, dokümanları, SQL şemalarını ve hatta PDF'leri sorgulanabilir bir bilgi grafiğine dönüştürerek bu sorunu başka bir yöntemle çözüyor.

Graphify Nedir?

Graphify, kod tabanınızı, dokümanlarını ve diğer dosyalarınızı bir bilgi grafiğine (knowledge graph) dönüştüren açık kaynak bir araç. GitHub'da Graphify-Labs/graphify adresinde geliştiriliyor. AI asistanınıza /graphify yazdığınızda tüm projeyi tarıyor ve karşınıza üç dosya çıkarıyor:

graphify-out/
├── graph.html       tarayıcıda açılır, tıklanabilir interaktif graf
├── GRAPH_REPORT.md  önemli kavramlar, şaşırtıcı bağlantılar, önerilen sorular
└── graph.json       sorgulanabilir graf verisi

Buradaki temel fikir şu: dosyaları tek tek okumak yerine, projeyi kavramlar ve bunlar arasındaki ilişkilerden oluşan bir graf olarak düşünmek. Bir düğüm (node) bir sınıf, fonksiyon, konfigürasyon ya da doküman parçası olabilir. Kenarlar (edge) ise bunların birbirini çağırma, içe aktarma ya da referans verme ilişkilerini taşır.

Vektör Veritabanı Değil, Gerçek Graf

Son iki yılda "kodu anlamak" için önerilen çözümlerin çoğu aynı yolu izliyor: dosyaları parçala, embedding üret, vektör veritabanına at, benzerlik araması yap. Graphify bu yola girmiyor. Embedding yok, vektör deposu yok. Bunun yerine tree-sitter ile AST düzeyinde deterministik bir ayrıştırma yapıyor ve gerçek bir graf üretiyor.

Bu yaklaşımın pratik sonucu, sorgulamanın benzerlik değil geçiş (traversal) üzerinden yapılması:

$ graphify explain "APIRouter"
Node: APIRouter
  Source:    routing.py L2210
  Community: 2
  Degree:    47

$ graphify path "FastAPI" "ModelField"
Shortest path (3 hops):
  FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField

graphify explain size bir kavramın ne olduğunu, nerede tanımlandığını ve neye bağlı olduğunu söyler. graphify path ise iki kavram arasındaki en kısa yolu adım adım gösterir. "FastAPI'den ModelField'a nasıl gidilir?" sorusuna vektör aramasıyla tutarlı cevap veremezsiniz, graf geçişiyle verebilirsiniz.

Her Kenar Açıklanıyor

Graphify'nin dikkat çeken yanı, ürettiği her kenara bir güven etiketi koyması:

  • EXTRACTED , ilişki doğrudan kaynaktan okundu. Kodda açık bir çağrı, import ya da referans var.
  • INFERRED , ilişki çözümleme ile türetildi. Kaynakta doğrudan yazmıyor ama graf çözümlemesi bunu üretti.

Bu ayrım önemli. AI asistanlarına güvenmek zorundaysak, en azından hangi bilginin dosyadan okunduğunu, hangisinin çıkarım olduğunu bilmek isteriz. Halüsinasyon riskini sıfırlamasa da "hangi bilgi ne kadar sağlam" sorusuna net bir çerçeve veriyor.

Kod Yerelde Kalıyor

Gizlilik tarafında Graphify'nin duruşu net: kod dosyaları tree-sitter ile tamamen yerelde ayrıştırılıyor. LLM çağrısı yok, hiçbir şey makinenizden çıkmıyor. Sadece kod içeren bir repo için API anahtarı bile gerekmiyor; graphify extract tamamen çevrimdışı çalışıyor.

Dokümanlar, PDF'ler, görseller ve video/audio içinse semantik bir geçiş var. Bu geçiş asistanınızın modelini kullanıyor ya da yapılandırdığınız bir API anahtarını. Video/audio transkripsiyonu faster-whisper ile yine yerelde yapılıyor. Telemetri, kullanım takibi, analitik yok.

Kurulum ve Kullanım

Kurulum iki adım:

uv tool install graphifyy      # CLI'ı kur (alternatif: pipx install graphifyy)
graphify install               # skill'i AI asistanına kaydet

Dikkat: PyPI paketi graphifyy (çift y). Diğer graphify* paketleri ilgili değil. CLI komutu yine graphify.

Sonra asistanınızda /graphify yazmanız yeterli. Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot dahil 20+ platformda çalışıyor. Kurulumdan sonra grafik sorgulamak için:

graphify query "auth ile veritabanı arasındaki bağ ne?"
graphify path "UserService" "DatabasePool"
graphify explain "RateLimiter"

Graf Neler İçeriyor?

  • God nodes , en çok bağlantısı olan kavramlar. Her şeyin neden akışının üzerinden geçtiğini gösterir.
  • Topluluklar (communities) , Leiden algoritmasıyla graf alt sistemlere bölünür. Renk kodlu alt sistem haritası demek.
  • Dosyalar arası bağlantılar , calls, imports, inherits, mixes_in kenarları tree-sitter AST ile ~40 dilde çözümlenir.
  • Gerekçe ve doküman referansları , # NOTE: ve # WHY: yorumları, ADR'ler ve RFC'ler birer düğüm olarak koda bağlanır.
  • Kodun ötesi , dokümanlar, PDF'ler, görseller ve video/audio aynı grafa girer.

Ekosistem Entegrasyonu

Graphify sadece bir kez çalışan bir araç değil. Takım kurulumu için graf çıktısının git'e commitlenmesi öneriliyor; herkes hazır bir harita ile başlıyor.

  • Git hook kurulumu: commit ve branch değişimlerinde graf otomatik yeniden inşa edilir (AST yeniden ayrıştırma, API maliyeti sıfır).
  • MCP sunucusu: python -m graphify.serve ile graf, asistanınıza MCP aracı olarak sunulur. HTTP taşıyıcısıyla takımın tamamı tek bir adrese bağlanabilir.
  • graphify prs: PR'ları graf topluluklarına göre çakışma ve merge sırası riski açısından inceleyen bir pano.
  • .graphifyignore: .gitignore sözdizimiyle grafa girmeyecek dosyaları belirlersiniz.

Kime Göre?

Yeni katıldığınız büyük bir repo, dokümana dökülmemiş on yıllık bir monolit ya da "bu sistemde kim neyi etkiliyor" sorusunun cevabı olmayan bir mikroservis kümesi varsa Graphify tam sizin için. Küçük ve tanıdık projelerde ekstra katman gereksiz olabilir. Ama kod tabanı büyüdükçe, dosya okuma yerine graf sorgulama, anlama hızını gerçekten değiştiriyor.

Açık kaynak, Apache-2.0 lisanslı. Repo: github.com/Graphify-Labs/graphify.

Paylaş