Thoth / README.md
mfirat007's picture
Upload 74 files
4a51f94 verified
|
Raw History Blame Contribute Delete
12.6 kB
metadata
title: Thoth
emoji: 📜
colorFrom: gray
colorTo: gray
sdk: docker
app_port: 7860
pinned: false

Thoth

Yapay zekâ destekli, Türkçe arayüzlü LaTeX yazım platformu. Akademisyenler, öğrenciler ve öğretmenler için: tarayıcıda yazın, derleyin, PDF'i yanında görün.

Varsayılan yazım biçimi APA 7'dir ve çıktılar siyah-beyazdır; kullanıcı başka bir biçim isterse belgesini değiştirebilir.

Özellikler

  • Editör: LaTeX renklendirme, komut / atıf / etiket tamamlama, biçimlendirme araç çubuğu, otomatik kaydetme.
  • Derleme ve önizleme: Sunucuda Tectonic ile derleme, yan panelde PDF. Hatalar dosya ve satırıyla, Türkçe açıklamalı gösterilir.
  • SyncTeX: Editördeki "PDF'te göster" düğmesi imlecin bulunduğu satırı PDF'te bulup vurgular; PDF'te bir yere çift tıklamak kaynak dosyada o satırı açar.
  • Şablonlar: APA 7 biçiminde boş belge, makale (profesyonel), tez ve ödev/rapor (öğrenci); siyah-beyaz sunum (Beamer) ve sınav kâğıdı. APA şablonları apa7 sınıfını ve biblatex-apa kaynakçasını kullanır; Türkçe APA yerelleştirmesi (vd., t.y., ss., Yüksek lisans tezi…) sunucuda hazırdır.
  • Kurum şablonları: Anadolu Üniversitesi Lisansüstü Eğitim Enstitüsü'nün tez ve dönem projesi yazım şablonları (Biçim-1). Enstitünün Word şablonlarındaki yerleşim (kenar boşlukları, başlık sayfaları, jüri/onay sayfası, özet, beyanlar, dizinler, Roma/Arap sayfa numaraları) ve Tez Yazım Kılavuzu'ndaki kurallar (5 başlık düzeyi, tablo/şekil/görsel başlıkları, uzun alıntı, kaynakça) anadolu-lee sınıfında uygulanır; şablon dosyaları server/sablonlar/ altındadır.
  • Yapay zekâ asistanı (ortak araştırmacı): Bilimsel ilkelere bağlı çalışır: iddialarını gerçek kaynaklara dayandırır; projenin kaynakçasında uygun kaynak yoksa OpenAlex, Crossref, arXiv ve OSF'de arar, yalnızca özeti iddiayı destekleyen kayıtlara atıf yapar ve bunları kendiliğinden .bib dosyasına ekler; kaynak bulamazsa bunu açıkça söyler. Hakemli dergi düzeyinde akademik dil kullanır (paragraf başı kalın başlık, madde listesiyle alanyazın ve Markdown yok); belirsiz isteklerde önce soru sorar; yöntemi eleştirel değerlendirir; bilimsel ya da etik açıdan uygun olmayan isteklerde uyarır ve gerekirse karşı çıkar. Açık dosyayı ve seçili metni görür; önerdiği değişiklik tek tıkla uygulanır; görseldeki denklem ya da tabloyu LaTeX'e çevirir. Claude ve OpenAI uyumlu uç noktalarla çalışır. Panelin genişliği kenarından sürüklenerek ayarlanır.
  • Kaynakça: OpenAlex, Crossref, arXiv ve OSF Preprints araması; kayıt .bib dosyasına eklenir, metne APA belgelerinde \parencite{}, diğerlerinde \cite{} konur.
  • Paylaşım: Projeyi e-postayla düzenleyici ya da görüntüleyici olarak paylaşma, metne iliştirilen yorumlar.
  • Sürüm geçmişi: Adlandırılmış sürümler, 10 dakikada bir otomatik kayıt, geri yükleme.
  • Biçimlendirme: Editördeki fırça düğmesi (Shift+Alt+F) tex-fmt ile girintileri ve boşlukları düzenler; paragraf satırları yeniden kırılmaz. Ctrl+Z ile geri alınır.
  • Word'e aktarma (APA 7): Üst çubuktaki "Word" düğmesi projeyi Pandoc ile .docx dosyasına çevirir. Belge APA 7 düzenindedir: Times New Roman 12 punto, çift satır aralığı, 2,54 cm kenar boşluğu, sağ üstte sayfa numarası (makalede kısa başlıkla), başlık sayfası, özet, numarasız APA başlık düzeyleri, "Tablo 1" / "Şekil 1" başlıkları, numaralı denklemler, İçindekiler ve asılı girintili "Kaynaklar" (APA 7 CSL stili, CC BY-SA 3.0).
  • Şablona giydir: Dergi ya da kurum şablonu yüklenir, çalışma (bu proje ya da bir Word dosyası) içeriği değiştirilmeden şablona aktarılır. Word şablonunda (.docx, .dotx) biçemler, kenar boşlukları ve üst/alt bilgiler şablondan alınır ve sonuç Word olarak iner (şablonun kapak gibi sabit sayfaları doldurulmaz). LaTeX şablonunda (.zip, .tex) yapay zekâ çalışmayı şablonun ana dosyasına yerleştirir, sonuç yeni proje olarak açılır; aktarılmayan metin varsa uyarı verilir.
  • İçe / dışa aktarma: .zip olarak proje alma ve verme.

Kurulum

Gereken: Node.js 24 ya da üstü.

npm install
npm run setup

npm run setup, sunucunun kullandığı dört açık kaynak aracı resmî sürümlerinden bin/ klasörüne indirir: Tectonic (derleyici), biber 2.17 (APA 7 kaynakçası; Tectonic 0.15'in biblatex sürümüyle uyumlu sürüm), tex-fmt (biçimlendirici) ve Pandoc (Word'e dönüştürme).

Ardından .env.example dosyasını .env adıyla kopyalayıp yapay zekâ için bir API anahtarı girin (asistan dışındaki her şey anahtarsız çalışır).

Çalıştırma

Geliştirme (arayüz http://localhost:5173, API 3001):

npm run dev

Üretim (arayüz ve API tek adreste, http://localhost:3001):

npm run build
npm start

Testler:

npm test

İlk derleme, gereken LaTeX paketleri internetten indirildiği için bir iki dakika sürebilir; sonrakiler hızlıdır.

Sunucuya taşıma

  1. Depoyu sunucuya kopyalayın; npm install, npm run setup, npm run build çalıştırın.
  2. Aşağıdaki güvenlik uyarısını uygulayın.
  3. .env içinde COOKIE_SECURE=true yapın ve uygulamayı HTTPS sonlandıran bir ters vekilin (nginx, Caddy) arkasına koyun. Ters vekil aynı makinedeyse HOST=127.0.0.1 kalabilir.
  4. npm start komutunu bir servis yöneticisiyle (systemd, pm2) sürekli çalıştırın.
  5. data/ klasörünü düzenli yedekleyin: veritabanı (thoth.db) ve tüm projeler buradadır.
  6. Kayıtları kapatmak için ALLOW_REGISTRATION=false yapın.

Hugging Face Space'te yayınlama

Depo, Docker Space olarak doğrudan çalışır (Dockerfile, bu dosyanın başındaki sdk: docker ve app_port: 7860).

  1. Space ayarlarında (Settings → Variables and secrets) şunları tanımlayın:
    • Secret ALLOWED_EMAILS: kayıt olabilecek e-postalar, virgülle ayrılmış.
    • Secret ANTHROPIC_API_KEY ve/veya OPENAI_API_KEY (yapay zekâ için).
    • Variable OPENAI_BASE_URL, OPENAI_MODEL (ör. Groq: https://api.groq.com/openai/v1, openai/gpt-oss-120b).
  2. Depoyu Space'e gönderin (git push). İmaj oluşturulurken araçlar indirilir ve şablon paketleri önbelleğe alınır; ilk oluşturma birkaç dakika sürer.
  3. Uygulamayı Space'in doğrudan adresinden açın: https://KULLANICI-thoth.hf.space. huggingface.co sayfasındaki gömülü görünümde tarayıcılar oturum çerezini engelleyebilir.
  4. https://KULLANICI-thoth.hf.space/api/saglik adresi derleme kafesinin durumunu gösterir; "ok": true olmalıdır.

Ücretsiz Space'te disk kalıcı değildir: Space yeniden başladığında (her güncellemede ya da uykudan uyanınca) hesaplar ve projeler silinir. Önemli projeleri .zip olarak indirin ya da Space'e bir depolama alanı (Storage Bucket, /data) bağlayıp DATA_DIR=/data yapın.

Güvenlik uyarısı: başkalarına açmadan önce

Derleyici (Tectonic) ve biber, --untrusted kipinde bile belgede mutlak yolla verilen dosyaları (\input{C:/...}, \addbibresource{/...}) okuyabilir; Tectonic \openout ile mutlak yola dosya da yazabilir. Platform birden çok kişiye açıldığında bu, bir kullanıcının sunucudaki dosyaları (ör. .env, veritabanı) kendi PDF'ine basabilmesi, hatta sunucu dosyalarının üzerine yazabilmesi demektir. Tectonic'in kendi ayarları bunu engellemez.

Bu yüzden sunucu varsayılan olarak yalnızca bu bilgisayardan erişilecek biçimde (HOST=127.0.0.1) çalışır; aynı ağdaki başka biri bağlanamaz. Word'e aktarma bu açıktan etkilenmez: Pandoc dosya erişimi kapalı kipte çalışır.

Derleme kafesi (Linux): COMPILE_SANDBOX=landlock ile her derleme bin/kafes içinde çalışır (kaynağı server/kafes.c). Kafes, Linux çekirdeğinin Landlock özelliğiyle derleyicinin ve biber'in yalnızca sistem kitaplıklarını, araçları, paket önbelleğini ve o projenin derleme klasörünü görmesine izin verir; uygulama kodu, veritabanı, diğer projeler ve /proc (sunucunun ortam değişkenleri) kapalıdır. Derleyiciye API anahtarları gibi ortam değişkenleri de geçirilmez. Sunucu açılışta kafesi sınar (/api/saglik); kafes çalışmıyorsa derleme kapatılır. Docker imajında bu ayar açıktır. Kalan risk: paket önbelleği projeler arasında ortaktır; bir kullanıcı önbelleğe dosya yazarak başka bir kullanıcının derlemesini etkileyebilir. Bu nedenle platformu yalnızca güvendiğiniz kişilere (ALLOWED_EMAILS) açın.

Ayarlar (.env)

Değişken Varsayılan Açıklama
ANTHROPIC_API_KEY – Claude için API anahtarı
ANTHROPIC_MODEL claude-opus-5-5 Kullanılacak Claude modeli
AI_EFFORT high Claude'un düşünme düzeyi (low, medium, high, xhigh, max)
OPENAI_API_KEY – OpenAI ya da uyumlu uç nokta anahtarı
OPENAI_BASE_URL OpenAI Uyumlu uç nokta adresi (ör. Ollama: http://localhost:11434/v1)
OPENAI_MODEL gpt-5.2 Kullanılacak model
OPENALEX_API_KEY – İsteğe bağlı OpenAlex anahtarı (anahtarsız da çalışır, günlük ortak kota daha düşüktür)
AI_HOURLY_LIMIT 60 Kullanıcı başına saatlik yapay zekâ isteği
PORT 3001 Sunucu kapısı
HOST 127.0.0.1 Sunucunun dinlediği adres; derleme yalıtılmadan ağa açmayın
ALLOW_REGISTRATION true Yeni hesap açılabilsin mi
ALLOWED_EMAILS – Doluysa yalnızca bu e-postalar kayıt olabilir (virgülle ayrılmış)
COMPILE_SANDBOX none landlock: derleme kafeste çalışır (Linux; Docker imajında açık)
COOKIE_SECURE false Oturum çerezi yalnızca HTTPS üzerinden gönderilsin mi
TECTONIC_BIN, TEXFMT_BIN, PANDOC_BIN bin/ Araçlar başka bir yere kuruluysa yolları
COMPILE_TIMEOUT_MS 180000 Derleme süre sınırı
DATA_DIR data Veri klasörü

Claude kullanılırken, model isteği güvenlik gerekçesiyle geri çevirirse API aynı isteği yedek bir modelde yeniden dener (sunucu taraflı fallbacks).

LaTeX notları

  • Derleyici XeTeX tabanlıdır: Türkçe için fontspec + polyglossia kullanın; inputenc / fontenc gerekmez.
  • Kaynakça varsayılan olarak biblatex + biber ile APA 7 biçiminde işlenir (\usepackage[style=apa,backend=biber]{biblatex}, \addbibresource{kaynakca.bib}, \printbibliography). natbib + BibTeX de çalışır.
  • Yazı tiplerini dosya adıyla yükleyin (ör. \setmainfont{texgyretermes}[Extension=.otf, ...]); sistem yazı tipi adları bulunamayabilir.
  • apa7 sınıfı Türkçe adları yalnızca babel ile yükler; polyglossia kullanan şablonlar bunları (\keywordname vb.) kendisi tanımlar.
  • server/tex/ klasöründeki destek dosyaları (Türkçe APA yerelleştirmesi turkish-apa.lbx) her derlemede projeye eklenir ve .zip dışa aktarmaya konur; projede aynı adda dosya varsa projeninki kullanılır.
  • Kabuk komutu çalıştırma (shell-escape) güvenlik nedeniyle kapalıdır; minted yerine listings kullanın.

Klasör yapısı

server/       Express API: hesaplar, projeler, derleme, yapay zekâ, kaynakça, geçmiş, Word
server/tex/   Derlemede projeye eklenen destek dosyaları (Türkçe APA yerelleştirmesi)
server/csl/   APA 7 kaynakça stili (Word'e aktarma)
web/          React + CodeMirror + PDF.js arayüzü
scripts/      Araç kurulum betiği
bin/          Tectonic, biber, tex-fmt, Pandoc (npm run setup ile gelir)
data/         Veritabanı, derleme çıktıları, paket önbelleği

Bilinen sınırlar

  • Eş zamanlı ortak düzenleme yoktur. Aynı dosyayı iki kişi düzenlerse sonradan kaydedene çakışma uyarısı gösterilir.
  • Word'e aktarma LaTeX'in yaygın yapılarını çevirir; özel makrolar, TikZ çizimleri ve PDF/EPS görseller Word'e taşınmaz (PDF görsellerin yerine belgede bir not çıkar). APA 4. ve 5. düzey başlıklar Word'de ayrı paragraf olarak yazılır (APA'da paragrafın başında yer alırlar). İçindekiler, Word'de alanlar güncellenince (F9) dolar.
  • Arayüz masaüstü ekranlar için tasarlanmıştır.