CopyGuard

İngilizce dokümantasyon: README.en.md

CopyGuard, Türkçe öğrenci ödevleri için yerel öncelikli kopya ve benzerlik analizi uygulamasıdır. Ders ve ödev bazında dosya yükler, analiz oturumlarını ayrı ayrı saklar, şüpheli çiftleri incelenebilir hale getirir ve HTML/CSV/SVG/PNG/tablo çıktıları üretir.

Öne Çıkanlar

• .docx, .pdf, .pptx, .md ve .txt dosyalarından metin çıkarma
• Türkçe metin temizleme, normalizasyon, shingle ve bölüm tespiti
• Hibrit analiz: MinHash, TF-IDF, embedding, bölüm skoru, blok örtüşmesi ve opsiyonel LLM yorumu
• Tam AI analizi: seçilen LLM sağlayıcısı ile çiftleri doğrudan değerlendirme
• Her analiz çalıştırmasını ayrı run olarak saklama ve eski sonuçlara geri dönebilme
• Hibrit ve Tam AI sonuçlarını yan yana karşılaştırma
• Canlı analiz durumu için SSE tabanlı arayüz güncellemesi
• Büyük raporlar için arama, filtreleme, sıralama ve sayfalı HTML tablo
• CSV, HTML rapor, görsel rapor ve tablo çıktıları

Gereksinimler

Gereksinim	Not
Python	3.11+
Backend paket yöneticisi	uv önerilir
Frontend	Node.js ve npm
LLM özellikleri	OpenRouter/OpenAI uyumlu veya Anthropic uyumlu API anahtarı
Embedding modeli	İlk kullanımda Hugging Face modeli indirilebilir

Hızlı Başlangıç

make install
cp .env.example .env
make start-all

Uygulama varsayılan olarak şu adreste açılır:

http://127.0.0.1:8000

Geliştirme modunda frontend ve backend ayrı süreçler olarak çalışır:

make dev

Geliştirme adresleri:

Servis	Adres
Frontend	http://localhost:3000
Backend API	http://127.0.0.1:8000

Ortam Ayarları

.env.example dosyasını .env olarak kopyalayıp gerekli değerleri düzenleyin. .env dosyası git tarafından yok sayılır; gerçek API anahtarlarını repoya eklemeyin.

Öne çıkan değişkenler:

Değişken	Açıklama
KOPYA_TESPIT_LLM_API_KEY	Tam AI veya LLM yorumları için sağlayıcı API anahtarı
KOPYA_TESPIT_OPENROUTER_API_KEY	Eski OpenRouter değişkeni; yedek olarak desteklenir
KOPYA_TESPIT_LLM_MODEL	Kullanılacak LLM modeli
KOPYA_TESPIT_LLM_API_BASE	OpenRouter/OpenAI/Anthropic uyumlu base URL veya tam endpoint
KOPYA_TESPIT_EMBEDDING_LOCAL_MODEL	Yerel sentence-transformers modeli
KOPYA_TESPIT_APP_DIR	Veritabanı, upload ve model cache klasörü

Varsayılan veri klasörü:

~/.kopya-tespit/

Bu klasörde SQLite veritabanı, yüklenen dosyalar, ayar dosyası ve yerel model cache tutulur.

Kullanım Akışı

1. Sol menüden ders oluşturun veya mevcut dersi seçin.
2. Ders altında bir ödev oluşturun.
3. Ödeve .docx, .pdf, .pptx, .md veya .txt dosyaları yükleyin.
4. Hazırlık sekmesinde analiz modunu seçin.
5. Analizi başlatın ve ilerlemeyi arayüzden takip edin.
6. İnceleme sekmesinde şüpheli çiftleri yan yana açın.
7. Çiftleri İşaretli veya İncelendi olarak işaretleyin.
8. Raporlar sekmesinden HTML, CSV, tablo, SVG veya PNG çıktı alın.

Analiz modları:

Mod	Açıklama
Hibrit hızlı	Yerel sinyallerle çalışır; LLM çağrıları varsayılan olarak kapalıdır
Tam AI	Çiftleri doğrudan LLM ile değerlendirir
İkisini karşılaştır	Hibrit ve Tam AI için iki run üretip sonuç farklarını gösterir

Paylaşıma Açık Materyaller

Demo dosyaları, benchmark verileri ve sunumlar tek noktada tutulur:

materials/

Klasör	İçerik
materials/sample-assignments/	Manuel test ve demo için örnek .docx ve .txt ödevler
materials/benchmarks/	Benchmark veri setleri, sonuç raporları ve ham çıktılar
materials/presentations/	Sunum HTML/PDF dosyaları ve konuşma/not metinleri

Ayrıntılı indeks için materials/README.md dosyasına bakın.

Raporlar

Rapor merkezi seçili analiz run'ına göre çalışır. Farklı zamanlarda çalıştırılan analizler birbirinin üstüne yazılmaz; run seçimi değiştirildiğinde rapor ve görsel linkleri o oturuma göre üretilir.

Çıktı	İçerik
HTML rapor	Pair arama, risk/durum filtresi, sıralama ve sayfalama
Çift skorları CSV	Tüm çift skorları
Yüksek risk CSV	Sadece yüksek riskli çiftler
Belge özeti CSV	Konu, anahtar kelime ve en yakın komşular
Görsel raporlar	Semantik ısı haritası, konu dağılımı, küme grafiği, dendrogram
Tablo görünümleri	Büyük veri setleri için SVG/PNG yerine sayfalı HTML tablo

Büyük veri setlerinde görseller otomatik olarak sınırlı sayıda belgeyle çizilir. Tam veri için HTML tablo ve CSV raporları kullanılmalıdır.

Komutlar

Komut	Açıklama
make install	Backend ve frontend bağımlılıklarını kurar
make dev	Frontend :3000 ve backend :8000 geliştirme sunucularını başlatır
make build	Next.js static export alır ve backend/static/ altına kopyalar
make start	Backend sunucusunu başlatır; önce build gerekir
make start-all	Frontend build + backend başlatma
python -m pytest	Testleri çalıştırır
ruff check backend tests	Backend lint kontrolü
npm --prefix frontend run lint	Frontend lint kontrolü
python -m backend.eval.benchmark	MinHash benchmark değerlendirmesi

API Özeti

Method	Path	Açıklama
GET	/api/health	Sağlık kontrolü
GET/POST	/api/courses	Ders listeleme ve oluşturma
GET/PATCH/DELETE	/api/courses/{id}	Ders detayı, güncelleme ve silme
POST	/api/courses/{id}/assignments	Ödev oluşturma
GET/PATCH/DELETE	/api/assignments/{id}	Ödev detayı, güncelleme ve silme
POST	/api/assignments/{id}/submissions	Dosya yükleme
POST	/api/assignments/{id}/analyze	Analiz başlatma
POST	/api/assignments/{id}/pause	Analizi duraklatma
POST	/api/assignments/{id}/resume	Analize devam etme
POST	/api/assignments/{id}/stop	Analizi yarıda bırakma
POST	/api/assignments/{id}/reset-analysis	Analiz sonuçlarını sıfırlama
GET	/api/assignments/{id}/events	Canlı analiz durumu
GET	/api/assignments/{id}/runs	Analiz run geçmişi
GET	/api/assignments/{id}/runs/compare	Hibrit ve Tam AI karşılaştırması
GET	/api/assignments/{id}/pairs?run_id=...	Seçili run çiftleri
GET	/api/assignments/{id}/report.html?run_id=...	HTML rapor
GET	/api/assignments/{id}/report.csv?run_id=...	CSV rapor
GET	/api/assignments/{id}/visuals/{name}.svg?run_id=...	Görsel SVG
GET	/api/assignments/{id}/visuals/{name}.png?run_id=...	Görsel PNG
GET	/api/pairs/{id}	Pair detayı ve tam metin
PATCH	/api/pairs/{id}	Pair durumunu güncelleme
GET/PUT	/api/settings	Ayarları okuma ve güncelleme

Dokümantasyon

Dosya	İçerik
docs/README.md	Dokümantasyon indeksi
docs/architecture.md	Runtime yapı, modül haritası ve analiz akışı
docs/configuration.md	Ortam değişkenleri ve ayar önceliği
backend/eval/README.md	Benchmark CLI notları
PLAN.md	Mimari plan ve tasarım kararları

Sınırlar

• Taranmış PDF/OCR kapsam dışıdır.
• Tam AI ve LLM yorumu için geçerli sağlayıcı API anahtarı gerekir.
• Yerel embedding modeli ilk kullanımda indirilebilir ve model boyutuna göre zaman alabilir.
• Çok büyük ödev setlerinde SVG/PNG görseller özetlenir; tam veri tablo ve CSV raporlarında tutulur.