sarraf 0.3.0

LLM çağında kalite filtresi — bilgi kirliliğinde kaliteli kaynak yargıcılığı

SARRAF

Bilgi güçtür, veri bilgidir. Prompt ve kaynak metni için LLM tabanlı kalite yargıcı. Flash × N=3 + Pro cascade ile yargılar, arşivde saklar, iyileştirme önerir, yeniden yazar.

Aktif sürüm: v0.3 (v1.0 yolu — bkz. MVP.md + ROADMAP.md + TODO.md)

---

Ne işe yarar?

• Prompt kalitesini ölç: 8 aspect × N=3 koşu → medyan agregasyon → band'dan verdict
• Hallüsinasyon engeli: Cascade arbiter (Gemini Pro) sınır durumlarda ikinci opinion
• Kendini besleyen arşiv: Accept + yeni kaynaklar otomatik discovered tier'a girer
• Öğrenme döngüsü: Kırmızı bayrak → öneri → yeniden yaz → tekrar tart
• Keşif: GitHub code search + Tavily web search ile yeni prompt bulma
• Proje etiketleme: GDYON / Meetink / MeyDey / yeni — arşiv filtreli

---

Hızlı başlangıç

1. .env dosyası oluştur (.env.example şablonundan):

GEMINI_API_KEY=sk-...        # zorunlu
GITHUB_TOKEN=ghp_...         # opsiyonel (keşif)
TAVILY_API_KEY=tvly-...      # opsiyonel (ikinci keşif kanalı)

2. Seed (opsiyonel — ilk arşiv):

py -m sarraf.scripts.seed_local        # GDYON + Sarraf promptları
py -m sarraf.scripts.seed_reference    # Claude cookbooks damıtma

3. Backend + Frontend:

# Terminal 1
py -m uvicorn backend.main:app --reload --port 8000

# Terminal 2
cd frontend/app && npm install && npm run dev
# http://localhost:5173

4. CLI (legacy — GUI'den bağımsız):

py -m sarraf.cli --text "Kaynak metni..." --profile academic --cascade --novelty
py -m sarraf.cli query "claude system prompt for coaching" --profile prompt_utility

---

Ana ekranlar

Ekran	Ne yapar
Ana sayfa	Hızlı giriş + son aktivite
Değerlendir	URL / Yapıştır / PDF / Ara — 4 mod
İlerleme	SSE akış: discover → judge → cascade → save
Sonuç	Aspect kırılımı + kırmızı bayrak + öneri + yeniden yaz + geçmiş + benzerler
Arşiv	3-tier corpus, künye, proje filtresi
Projeler	Etiket CRUD (GDYON / Meetink / MeyDey / yeni)
Ayarlar	Env durumu + cache + maliyet özeti
Onboarding	İlk kurulum (anahtar kontrol)

---

API özeti

GET  /health
GET  /corpus/counts, list, {id}
POST /corpus/{id}/summarize            — LLM künye
POST /corpus/similar                   — semantik en-yakın
GET  /corpus/{id}/projects             — entry etiketleri
PUT  /corpus/{id}/projects             — entry etiketlerini replace

GET/POST/PUT/DELETE /projects          — etiket CRUD

POST /evaluate                         — tek kaynak yargı (senkron)
POST /evaluate/url                     — URL (HTML + PDF)
POST /evaluate/pdf                     — multipart PDF upload
POST /evaluate/improve                 — per-flag öneri
POST /evaluate/rewrite                 — tam yeniden yaz
GET  /evaluate/{source_id}             — kalıcı sonuç (refresh-safe)
GET  /evaluate/{source_id}/history     — prompt evolution zinciri

POST /query                            — discover+judge+cascade SSE
GET  /query/{hash}                     — cache'ten sonuç

GET  /settings                         — env + corpus + cache
GET  /settings/usage?days=30           — LLM maliyet özeti
POST /settings/purge                   — query cache purge

---

Klasör ağacı

sarraf/                       # Çekirdek Python paketi
├── core/                     # Saf fonksiyon + LLM çağrıları
│   ├── pre_judge.py          # D3 jüri izolasyonu
│   ├── judge.py              # Flash × N=3 + D yaması + fail-safe
│   ├── cascade.py            # Pro arbiter (boundary/failsafe)
│   ├── novelty.py            # 3-tier novelty classify
│   ├── embeddings.py         # gemini-embedding-001 (768 dim)
│   ├── discover.py           # GitHub + Tavily kaynak keşfi
│   ├── profiles.py           # academic | prompt_utility
│   ├── improve.py            # per-flag iyileştirme önerisi
│   ├── rewrite.py            # tam prompt yeniden yazma
│   ├── summarize.py          # arşiv künye üretimi
│   ├── harvard.py            # Harvard preview iskelet
│   ├── usage.py              # Kullanım sentezi (applicable_projects...)
│   └── dedup.py              # semantic red-flag dedup
├── models/verdict.py         # Pydantic şemaları (tek kaynak)
├── store/                    # SQLite katmanı
│   ├── sqlite.py
│   ├── api_evaluations.py    # /result/:id + parent_source_id history
│   ├── corpus.py             # 3-tier + sqlite-vec
│   ├── query_cache.py
│   ├── projects.py           # proje etiketleri + M2M
│   └── usage_log.py          # LLM maliyet kaydı
├── scripts/seed_local, seed_reference
└── cli.py                    # legacy + query

backend/                      # FastAPI
├── main.py                   # router mount + CORS
└── api/corpus,projects,cache,evaluate,query,settings.py

frontend/app/                 # Vite + React + TS + Tailwind
├── src/
│   ├── components/           # TopAppBar, VerdictBadge, ErrorBoundary...
│   ├── screens/              # Home, Onboarding, Submit, Progress,
│   │                         #   Result, Archive, Projects, Settings
│   ├── lib/api.ts            # Backend API client + SSE parser
│   └── styles/
└── tailwind.config.js        # Stitch palette

tests/                        # pytest 155+ PASS
MVP.md, ROADMAP.md, TODO.md   # Yol haritası — v1.0'a kadar sistematik takip
sarraf_v03_backlog.md         # Tarihsel karar gerekçeleri
CLAUDE.md                     # Proje kuralları (mimari kilitler + S1-S7)
.env.example                  # Ortam şablonu
sarraf.db                     # SQLite (evaluations + corpus + cache + projects + usage)

---

Mimari kilitler (değiştirmeden önce CLAUDE.md oku)

1. Jüri saf fonksiyon — user comment pre_judge sanitize
2. overall_score LLM'den değil — aspect medyan ortalaması (Tur 5 D)
3. Verdict computed overall band'dan — fail-safe override korunur
4. Fail-safe: ≥2 aspect kayması → reweigh + cascade
5. Üretim prompt'u Türkçe (İngilizce rollback'ten sonra)
6. Red-flag normalize: NFKD + casefold + parantez strip (S3 Türkçe için)

---

v1.0 yolu

• Faz 1 — Kalite: Self-referential fix + boundary instability + embedding dedup
• Faz 2 — Ölçüm: D6 maliyet + D4c determinizm + C4 dil + C5 novelty
• Faz 3 — Cila: ✅ rewrite + history + PDF + persistent result + onboarding + ErrorBoundary
• Faz 4 — Kapsam: ✅ proje etiketleme + usage infra → UI dashboard + Harvard iskelet

Detay: ROADMAP.md.

---

Lisans + katkı

Solo + özel — v1.0'da değerlendirilecek. Geri bildirim: issue açma öncesi CLAUDE.md §Project-Specific Rules oku.