Metadata-Version: 2.4
Name: sarraf
Version: 0.3.0
Summary: LLM çağında kalite filtresi — bilgi kirliliğinde kaliteli kaynak yargıcılığı
Project-URL: Homepage, https://github.com/aximity/sarraf
Project-URL: Repository, https://github.com/aximity/sarraf
Project-URL: Issues, https://github.com/aximity/sarraf/issues
Author-email: Ahmet Hakan Yıldız <memed.akif78@gmail.com>
License: MIT
Keywords: claude-code,evaluation,gemini,llm,mcp,prompt-engineering,quality,research
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: fastmcp>=3.0
Requires-Dist: google-genai>=0.4
Requires-Dist: pdfplumber>=0.11
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: requests>=2.31
Requires-Dist: sqlite-vec>=0.1.6
Provides-Extra: backend
Requires-Dist: fastapi>=0.110; extra == 'backend'
Requires-Dist: python-multipart>=0.0.9; extra == 'backend'
Requires-Dist: uvicorn[standard]>=0.27; extra == 'backend'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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](./MVP.md) + [ROADMAP.md](./ROADMAP.md) + [TODO.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](./.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):**

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

**3. Backend + Frontend:**

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

```bash
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](./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](./ROADMAP.md).

---

## Lisans + katkı

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