embedpick 0.1.0__py3-none-any.whl

embedpick/__init__.py

@@ -0,0 +1,7 @@
+"""embedpick — kendi verinizde embedding modeli kıyaslama aracı."""
+
+from .benchmark import run_benchmark
+from .data import load_corpus, load_queries, validate
+
+__version__ = "0.1.0"
+__all__ = ["run_benchmark", "load_corpus", "load_queries", "validate"]

embedpick/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

embedpick/benchmark.py

@@ -0,0 +1,97 @@
+"""Benchmark akışını yürütür ve sonuç tablosunu üretir."""
+
+import pandas as pd
+
+from .metrics import consensus_failures, recall_at_k, score_all
+from .retrievers import BM25Retriever, EmbeddingRetriever
+
+
+def run_benchmark(
+    corpus,
+    queries,
+    model_names,
+    k=5,
+    repeats=5,
+    include_baseline=True,
+    use_presets=True,
+    verbose=False,
+):
+    retrievers = []
+    if include_baseline:
+        retrievers.append(BM25Retriever())
+
+    for name in model_names:
+        if use_presets:
+            retrievers.append(EmbeddingRetriever(name))
+        else:
+            # Önekler kapalı: modelin belgelenmiş kullanım kuralı yok sayılıyor.
+            # Yanlış yapılandırmanın maliyetini ölçmek için.
+            retrievers.append(EmbeddingRetriever(name, query_prefix="", doc_prefix=""))
+
+    satirlar = []
+    sorgu_bazli = {}
+
+    for retriever in retrievers:
+        print(f"\n-> {retriever.label}")
+        maliyet = retriever.index(corpus, repeats)
+        bulunanlar = retriever.search(queries["query"].tolist(), k)
+
+        recall, mrr = score_all(bulunanlar, queries, k, verbose=verbose)
+
+        sorgu_bazli[retriever.label] = {
+            q: recall_at_k(bulunan, dogru, k)
+            for q, bulunan, dogru in zip(
+                queries["query"], bulunanlar, queries["relevant_ids"]
+            )
+        }
+
+        satirlar.append(
+            {
+                "model": retriever.label,
+                f"recall@{k}": round(recall, 3),
+                f"mrr@{k}": round(mrr, 3),
+                "docs_per_sec": round(maliyet["docs_per_sec"], 1),
+                "dim": maliyet["dim"],
+                "index_mb": round(maliyet["index_mb"], 2),
+            }
+        )
+
+    _add_relative_speed(satirlar)
+    return pd.DataFrame(satirlar), sorgu_bazli
+
+
+def _add_relative_speed(satirlar):
+    """Mutlak hız makineye ve o anki işlemci durumuna göre kat kat oynar.
+    Aynı çalıştırma içindeki oranlar ise sabit kalır."""
+    sinirsel = [r for r in satirlar if r["dim"] > 0]
+    if not sinirsel:
+        return
+
+    en_hizli = max(r["docs_per_sec"] for r in sinirsel)
+    for r in satirlar:
+        r["rel_speed"] = f"{r['docs_per_sec'] / en_hizli:.2f}x" if r["dim"] > 0 else "-"
+
+
+def report(df, sorgu_bazli, k):
+    print()
+    print(df.to_string(index=False))
+
+    print(
+        "\nNot: docs_per_sec makineye ve o anki işlemci durumuna göre değişir."
+        "\n     Makineler arası kıyas için rel_speed sütununu kullanın"
+        "\n     (en hızlı sinirsel model = 1.00x)."
+    )
+
+    # Tek yöntem varken "hiçbiri bulamadı" demek anlamsız; uyarının değeri
+    # birden fazla yöntemin aynı sorguda batmasından geliyor.
+    ortak = consensus_failures(sorgu_bazli) if len(sorgu_bazli) > 1 else []
+    if ortak:
+        print(
+            f"\nHiçbir yöntemin ilk {k} sonuçta bulamadığı sorgular:"
+        )
+        for q in ortak:
+            print(f"  - {q}")
+        print(
+            "  Bütün yöntemler aynı sorguda batıyorsa sorun genelde modelde değil,"
+            "\n  etiketlerdedir. Bu sorguların relevant_ids değerlerini gözden geçirin."
+        )

embedpick/cli.py

@@ -0,0 +1,111 @@
+"""embedpick komut satırı arayüzü."""
+
+import argparse
+import sys
+from importlib import resources
+
+from .benchmark import report, run_benchmark
+from .data import load_corpus, load_queries, validate
+from .retrievers import DEFAULT_MODELS
+
+
+def sample_path(name):
+    """Pakete gömülü örnek veri dosyasının yolu.
+
+    Paket pip ile kurulduğunda çalışma dizininde data/ klasörü olmaz,
+    o yüzden varsayılan veri kurulum dizininden okunuyor.
+    """
+    return str(resources.files("embedpick") / "sample_data" / name)
+
+
+def build_parser():
+    p = argparse.ArgumentParser(
+        prog="embedpick",
+        description=(
+            "Kendi verinizde embedding modellerini kıyaslayın. "
+            "Kalite, hız ve bellek maliyetini tek tabloda gösterir."
+        ),
+    )
+    p.add_argument(
+        "--corpus",
+        help="Aranacak dokümanlar (sütunlar: id,text). "
+        "Verilmezse pakete gömülü örnek veri kullanılır.",
+    )
+    p.add_argument(
+        "--queries",
+        help="Sorgular ve doğru cevaplar (sütunlar: query,relevant_ids). "
+        "Verilmezse pakete gömülü örnek veri kullanılır.",
+    )
+    p.add_argument(
+        "--models",
+        nargs="+",
+        default=DEFAULT_MODELS,
+        help="Hugging Face model adları, boşlukla ayrılmış",
+    )
+    p.add_argument("-k", type=int, default=5, help="İlk kaç sonuç değerlendirilsin")
+    p.add_argument(
+        "--repeats", type=int, default=5, help="Hız ölçümü kaç kez tekrarlansın"
+    )
+    p.add_argument(
+        "--no-baseline",
+        action="store_true",
+        help="BM25 kelime bazlı baseline'ı atla (önerilmez)",
+    )
+    p.add_argument(
+        "--no-presets",
+        action="store_true",
+        help=(
+            "Bilinen model öneklerini uygulama. e5 gibi önek bekleyen modeller "
+            "düşük skor alır; yanlış yapılandırmanın maliyetini ölçmek için."
+        ),
+    )
+    p.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Her sorgunun sonucunu tek tek yazdır",
+    )
+    p.add_argument("--out", help="Sonuç tablosunu CSV olarak kaydet")
+    return p
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+
+    corpus_path = args.corpus or sample_path("corpus.csv")
+    queries_path = args.queries or sample_path("queries.csv")
+
+    if args.corpus is None and args.queries is None:
+        print("Kendi veriniz verilmedi, pakete gömülü örnek veri kullanılıyor.")
+
+    try:
+        corpus = load_corpus(corpus_path)
+        queries = load_queries(queries_path)
+        validate(corpus, queries)
+    except (FileNotFoundError, ValueError) as exc:
+        print(f"Hata: {exc}", file=sys.stderr)
+        return 1
+
+    print(f"{len(corpus)} doküman, {len(queries)} sorgu, k={args.k}")
+
+    df, sorgu_bazli = run_benchmark(
+        corpus,
+        queries,
+        model_names=args.models,
+        k=args.k,
+        repeats=args.repeats,
+        include_baseline=not args.no_baseline,
+        use_presets=not args.no_presets,
+        verbose=args.verbose,
+    )
+
+    report(df, sorgu_bazli, args.k)
+
+    if args.out:
+        df.to_csv(args.out, index=False, encoding="utf-8")
+        print(f"\nTablo kaydedildi: {args.out}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

embedpick/data.py

@@ -0,0 +1,69 @@
+"""Korpus ve sorgu dosyalarını okur, formatlarını doğrular."""
+
+import pandas as pd
+
+
+def load_corpus(path):
+    df = pd.read_csv(path, encoding="utf-8")
+
+    missing = {"id", "text"} - set(df.columns)
+    if missing:
+        raise ValueError(
+            f"{path} dosyasında eksik sütun: {sorted(missing)}. "
+            "Beklenen başlık satırı: id,text"
+        )
+
+    if df["id"].duplicated().any():
+        tekrar = df.loc[df["id"].duplicated(), "id"].tolist()
+        raise ValueError(f"{path} içinde tekrar eden id değerleri var: {tekrar}")
+
+    df["text"] = df["text"].astype(str).str.strip()
+    return df
+
+
+def load_queries(path):
+    df = pd.read_csv(path, encoding="utf-8")
+
+    missing = {"query", "relevant_ids"} - set(df.columns)
+    if missing:
+        raise ValueError(
+            f"{path} dosyasında eksik sütun: {sorted(missing)}. "
+            "Beklenen başlık satırı: query,relevant_ids"
+        )
+
+    df["query"] = df["query"].astype(str).str.strip()
+    df["relevant_ids"] = df["relevant_ids"].apply(_parse_ids)
+    return df
+
+
+def _parse_ids(value):
+    parts = [p.strip() for p in str(value).split(";") if p.strip()]
+    if not parts:
+        raise ValueError(f"Boş relevant_ids değeri bulundu: {value!r}")
+    try:
+        return [int(p) for p in parts]
+    except ValueError as exc:
+        raise ValueError(
+            f"relevant_ids sayı olmalı, alınan: {value!r}. "
+            "Birden fazla id noktalı virgülle ayrılır, örnek: 3;11"
+        ) from exc
+
+
+def validate(corpus, queries):
+    """Sorgu etiketlerinin korpusta gerçekten var olduğunu kontrol eder.
+
+    Etiket hataları benchmark sonuçlarını sessizce bozar: olmayan bir id'yi
+    hiçbir model bulamaz, sen de modeli suçlarsın. Baştan yakalamak daha iyi.
+    """
+    bilinen = set(corpus["id"])
+    sorunlar = []
+
+    for q, ids in zip(queries["query"], queries["relevant_ids"]):
+        eksik = [i for i in ids if i not in bilinen]
+        if eksik:
+            sorunlar.append(f'  "{q}" -> korpusta olmayan id: {eksik}')
+
+    if sorunlar:
+        raise ValueError(
+            "Sorgu etiketleri korpusla uyuşmuyor:\n" + "\n".join(sorunlar)
+        )

embedpick/metrics.py

@@ -0,0 +1,54 @@
+"""Erişim metrikleri: recall@k ve MRR@k."""
+
+import numpy as np
+
+
+def recall_at_k(retrieved_ids, relevant_ids, k):
+    """İlk k sonuçta doğru dokümanların ne kadarı yakalandı."""
+    hits = len(set(retrieved_ids[:k]) & set(relevant_ids))
+    return hits / len(relevant_ids)
+
+
+def reciprocal_rank(retrieved_ids, relevant_ids, k):
+    """İlk doğru sonucun sırasının tersi. 1. sıra -> 1.0, 2. sıra -> 0.5."""
+    for rank, doc_id in enumerate(retrieved_ids[:k], start=1):
+        if doc_id in relevant_ids:
+            return 1.0 / rank
+    return 0.0
+
+
+def score_all(all_retrieved, queries, k, verbose=False):
+    """Tüm sorguları puanlar, ortalama recall ve MRR döndürür."""
+    recalls = []
+    rrs = []
+
+    for q, retrieved_ids, relevant in zip(
+        queries["query"], all_retrieved, queries["relevant_ids"]
+    ):
+        r = recall_at_k(retrieved_ids, relevant, k)
+        rr = reciprocal_rank(retrieved_ids, relevant, k)
+        recalls.append(r)
+        rrs.append(rr)
+        if verbose:
+            print(
+                f"   [r={r:.2f} rr={rr:.2f}] {q}"
+                f"  -> {retrieved_ids}  | doğru: {relevant}"
+            )
+
+    return float(np.mean(recalls)), float(np.mean(rrs))
+
+
+def consensus_failures(per_model_scores, threshold=0.0):
+    """Hiçbir modelin bulamadığı sorguları döndürür.
+
+    Bütün modeller aynı sorguda batıyorsa suçlu genelde model değil, etikettir.
+    """
+    if not per_model_scores:
+        return []
+
+    sorgular = list(per_model_scores.values())[0].keys()
+    return [
+        q
+        for q in sorgular
+        if all(skorlar[q] <= threshold for skorlar in per_model_scores.values())
+    ]

embedpick/retrievers.py

@@ -0,0 +1,150 @@
+"""Arama yöntemleri: kelime bazlı BM25 baseline ve embedding tabanlı arama."""
+
+import re
+import time
+
+import numpy as np
+
+# Bazı modeller metinlerin başına önek bekler. Önek konmazsa model kötü
+# çalışır ve kullanıcı bunu "model kötüymüş" diye yorumlar. Bilinenleri
+# burada tutuyoruz ki varsayılan davranış doğru olsun.
+MODEL_PRESETS = {
+    "intfloat/multilingual-e5-small": {"query": "query: ", "doc": "passage: "},
+    "intfloat/multilingual-e5-base": {"query": "query: ", "doc": "passage: "},
+    "intfloat/multilingual-e5-large": {"query": "query: ", "doc": "passage: "},
+    "BAAI/bge-m3": {"query": "", "doc": ""},
+}
+
+DEFAULT_MODELS = [
+    "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
+    "intfloat/multilingual-e5-small",
+    "trmteb/turkish-embedding-model",
+]
+
+
+def get_prefixes(model_name):
+    if model_name in MODEL_PRESETS:
+        return MODEL_PRESETS[model_name]
+
+    # Tanımadığımız bir e5 varyantı gelirse yine de uyaralım.
+    if "e5" in model_name.lower():
+        print(
+            f"   uyarı: {model_name} bir e5 varyantı gibi görünüyor. "
+            "e5 modelleri 'query: ' / 'passage: ' öneki bekler, "
+            "önek olmadan skorlar düşük çıkar."
+        )
+    return {"query": "", "doc": ""}
+
+
+def tr_tokenize(text):
+    """Türkçe farkındalıklı basit kelime ayırıcı.
+
+    Python'un lower() metodu Türkçe bilmez: "I" -> "i" yapar, oysa "ı" olmalı.
+    "İ" ise "i" artı ayrı bir birleşen nokta karakterine bölünür.
+    """
+    text = text.replace("I", "ı").replace("İ", "i")
+    return re.findall(r"\w+", text.lower(), flags=re.UNICODE)
+
+
+class BM25Retriever:
+    """Kelime bazlı baseline. Embedding modelleri bunu geçemiyorsa
+    harcanan hesap gücü boşa gidiyor demektir."""
+
+    label = "BM25 (baseline)"
+    dim = 0
+
+    def __init__(self):
+        self._bm25 = None
+        self._ids = None
+
+    def index(self, corpus, repeats):
+        from rank_bm25 import BM25Okapi
+
+        texts = corpus["text"].tolist()
+        timings = []
+        for _ in range(repeats):
+            start = time.perf_counter()
+            tokenized = [tr_tokenize(t) for t in texts]
+            bm25 = BM25Okapi(tokenized)
+            timings.append(time.perf_counter() - start)
+
+        self._bm25 = bm25
+        self._ids = corpus["id"].tolist()
+
+        index_sec = float(np.median(timings))
+        return {
+            "docs_per_sec": len(texts) / index_sec,
+            "index_mb": 0.0,
+            "dim": 0,
+        }
+
+    def search(self, queries, k):
+        sonuclar = []
+        for q in queries:
+            scores = self._bm25.get_scores(tr_tokenize(q))
+            top = np.argsort(-scores)[:k]
+            sonuclar.append([self._ids[i] for i in top])
+        return sonuclar
+
+
+class EmbeddingRetriever:
+    """sentence-transformers modeli + FAISS iç çarpım indeksi.
+
+    Vektörler normalize edildiği için iç çarpım = kosinüs benzerliği.
+    """
+
+    def __init__(self, model_name, query_prefix=None, doc_prefix=None):
+        self.model_name = model_name
+        self.label = model_name.split("/")[-1]
+
+        onekler = get_prefixes(model_name)
+        self.query_prefix = onekler["query"] if query_prefix is None else query_prefix
+        self.doc_prefix = onekler["doc"] if doc_prefix is None else doc_prefix
+
+        self._model = None
+        self._index = None
+        self._ids = None
+        self.dim = 0
+
+    def index(self, corpus, repeats):
+        from sentence_transformers import SentenceTransformer
+
+        self._model = SentenceTransformer(self.model_name)
+        texts = [self.doc_prefix + t for t in corpus["text"].tolist()]
+
+        # Isınma: tüm korpusu bir kez geçiyoruz. Kısa bir ısınma turu
+        # işlemciyi düşük frekanstan çıkarmaya yetmiyor ve ilk ölçümler
+        # yanıltıcı derecede yavaş çıkıyor.
+        self._encode(texts)
+
+        # Medyan alıyoruz; ortalama tek bir tepe değerden bozulur.
+        timings = []
+        for _ in range(repeats):
+            start = time.perf_counter()
+            emb = self._encode(texts)
+            timings.append(time.perf_counter() - start)
+
+        import faiss
+
+        self.dim = int(emb.shape[1])
+        self._index = faiss.IndexFlatIP(self.dim)
+        self._index.add(np.asarray(emb, dtype="float32"))
+        self._ids = corpus["id"].tolist()
+
+        encode_sec = float(np.median(timings))
+        return {
+            "docs_per_sec": len(texts) / encode_sec,
+            "index_mb": emb.nbytes / (1024 * 1024),
+            "dim": self.dim,
+        }
+
+    def search(self, queries, k):
+        texts = [self.query_prefix + q for q in queries]
+        emb = self._encode(texts)
+        _, positions = self._index.search(np.asarray(emb, dtype="float32"), k)
+        return [[self._ids[p] for p in row] for row in positions]
+
+    def _encode(self, texts):
+        return self._model.encode(
+            texts, normalize_embeddings=True, show_progress_bar=False
+        )

embedpick/sample_data/corpus.csv

@@ -0,0 +1,73 @@
+id,text
+1,Kargom hala elime ulaşmadı
+2,Sipariş takip numaram sistemde görünmüyor
+3,Paketim yanlış adrese teslim edilmiş
+4,Kurye kapıyı çalmadan teslim edilemedi olarak işaretlemiş
+5,Teslimat tarihi sürekli ileriye atılıyor
+6,Kargo firmasını değiştirebilir miyim
+7,Siparişim iki ayrı paket halinde mi gelecek
+8,Şubeden teslim alma seçeneği var mı
+9,Gönderim ücreti neden bu kadar yüksek
+10,Yurt dışına gönderim yapıyor musunuz
+11,İade sürecini nasıl başlatabilirim
+12,Ürünü kaç gün içinde geri gönderebilirim
+13,Beden değişimi yapmak mümkün mü
+14,İade kargo ücretini kim karşılıyor
+15,Geri gönderdiğim ürün elinize ulaştı mı
+16,Paramı ne zaman geri alacağım
+17,Kullanılmış ürün iade edilebilir mi
+18,Hediye olarak aldığım ürünü değiştirebilir miyim
+19,İade formunu nereden indirebilirim
+20,Farklı renk ile değişim yapmak istiyorum
+21,Kredi kartımdan iki kez çekim yapılmış
+22,Fatura adresimi değiştirmek istiyorum
+23,Ödemem onaylandı ama sipariş görünmüyor
+24,Taksit seçenekleri neden çıkmıyor
+25,Kapıda ödeme yapabilir miyim
+26,Kurumsal fatura kesilmesini istiyorum
+27,Havale ile ödeme yaptım ama onaylanmadı
+28,Kartımdan çekilen tutar sipariş tutarından fazla
+29,E-arşiv faturama nereden ulaşırım
+30,Ödeme sayfasında hata alıyorum
+31,Şifremi unuttum giriş yapamıyorum
+32,Hesabım askıya alınmış neden
+33,Üyeliğimi tamamen silmek istiyorum
+34,E-posta adresimi güncellemek istiyorum
+35,Doğrulama kodu telefonuma gelmiyor
+36,Aynı e-posta ile ikinci hesap açabilir miyim
+37,Hesabıma başkası girmiş olabilir
+38,Telefon numaramı değiştiremiyorum
+39,Bildirim tercihlerimi nereden ayarlarım
+40,Üyelik avantajları nelerdir
+41,Ürün hasarlı geldi kutusu ezilmişti
+42,Ürün açıklamadaki renkten farklı geldi
+43,Gelen üründe eksik parça var
+44,Ürünün orijinal olmadığını düşünüyorum
+45,Ambalaj açılmış görünüyor
+46,Ürün ilk kullanımda bozuldu
+47,Beden tablosu gerçeği yansıtmıyor
+48,Ürün fotoğraftakinden çok daha küçük
+49,Kumaş kalitesi beklediğim gibi değil
+50,Son kullanma tarihi geçmiş ürün gönderilmiş
+51,Kampanya kodu sepette geçerli olmadı
+52,İndirimli aldığım ürün sipariş sonrası zamlandı
+53,Hediye çekimi nasıl kullanırım
+54,Bedava gönderim kampanyası devam ediyor mu
+55,Sepetimdeki ürünün fiyatı değişti
+56,Bu ürün iki al bir öde kampanyasına dahil mi
+57,Puanlarım hesabıma yansımadı
+58,Öğrenci indirimi var mı
+59,Garanti kapsamında tamir talebi oluşturmak istiyorum
+60,Garanti belgesi paketten çıkmadı
+61,En yakın yetkili servis nerede
+62,Garanti süresi ne kadar
+63,Tamire gönderdiğim ürün ne zaman döner
+64,Garanti kapsamı dışında olduğu söylenip ücret istendi
+65,Ürünün yedek parçasını nereden alabilirim
+66,Kullanım kılavuzuna nereden ulaşabilirim
+67,Siparişimi iptal etmek istiyorum
+68,Tükenen ürün tekrar gelecek mi
+69,Teslimat adresimi güncelleyebilir miyim
+70,Siparişime ürün ekleyebilir miyim
+71,Ön sipariş verdiğim ürün ne zaman gönderilir
+72,Müşteri hizmetlerine nasıl ulaşabilirim

embedpick/sample_data/queries.csv

@@ -0,0 +1,27 @@
+query,relevant_ids
+kargo gecikmesi,1;5
+paketim nerede,1;2
+yanlış adrese teslimat,3
+paramı geri istiyorum,16;11
+ürünü geri göndermek istiyorum,11;12
+kıyafet küçük geldi,47;48
+çift çekim yapıldı,21;28
+fatura bilgilerimi güncelleme,22;29
+hesabıma giremiyorum,31;35
+güvenlik ihlali şüphesi,37
+bozuk ürün geldi,46;41
+kutu ezilmiş halde geldi,41;45
+renk farklı,42;20
+indirim kodu çalışmıyor,51;53
+ücretsiz kargo,54;9
+tamir ve servis,59;61;63
+siparişi durdurmak istiyorum,67
+adres değiştirme,69;22
+ürün ne zaman stoklara girecek,68
+size nasıl ulaşabilirim,72
+taksitli alışveriş,24
+ödeme yaparken sorun,30;27
+üyelikten çıkmak istiyorum,33
+sahte ürün şüphesi,44
+yurt dışı gönderim,10
+garanti süresi,62;60

embedpick-0.1.0.dist-info/METADATA

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: embedpick
+Version: 0.1.0
+Summary: Benchmark embedding models on your own data, with a keyword-search baseline
+Author: Mehmet Alper Tuğtekin
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Mehmetalpertugtekin/embedpick
+Project-URL: Repository, https://github.com/Mehmetalpertugtekin/embedpick
+Project-URL: Issues, https://github.com/Mehmetalpertugtekin/embedpick/issues
+Keywords: embeddings,benchmark,semantic-search,information-retrieval,sentence-transformers,turkish-nlp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Natural Language :: Turkish
+Classifier: Natural Language :: English
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.3
+Requires-Dist: numpy>=1.21
+Requires-Dist: rank-bm25>=0.2
+Requires-Dist: sentence-transformers>=2.2
+Requires-Dist: faiss-cpu>=1.7
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Provides-Extra: ui
+Requires-Dist: gradio>=4.0; extra == "ui"
+Dynamic: license-file
+
+# embedpick
+![tests](https://github.com/Mehmetalpertugtekin/embedpick/actions/workflows/tests.yml/badge.svg)
+
+Benchmark embedding models on **your own data**, not on someone else's leaderboard.
+
+[Türkçe README](README.tr.md)
+
+## Why
+
+Picking an embedding model usually goes like this: open Hugging Face, sort by
+downloads, take the top result. The scores on the model card were measured on
+general-purpose English benchmarks. Your data is not that.
+
+embedpick answers a narrower and more useful question: *given my documents and
+my queries, which model actually finds the right thing, and what does it cost
+me in time and memory?*
+
+It reports quality, speed and memory side by side, and — unlike most benchmark
+tooling — it puts a plain keyword-search baseline in the same table.
+
+## The baseline is the point
+
+Every run includes BM25, a classic keyword-matching algorithm with no neural
+network involved. If an embedding model cannot beat it, running that model is
+wasted compute.
+
+Results on the included Turkish customer-support dataset (72 documents,
+26 queries, k=5):
+
+| Model | recall@5 | MRR@5 | docs/sec | dim | rel. speed |
+|---|---|---|---|---|---|
+| BM25 (baseline) | 0.564 | 0.564 | ~226,000 | — | — |
+| paraphrase-multilingual-MiniLM-L12-v2 | 0.615 | 0.596 | 340 | 384 | 1.00x |
+| multilingual-e5-small | 0.692 | 0.708 | 304 | 384 | 0.89x |
+| trmteb/turkish-embedding-model | **0.846** | **0.865** | 103 | 768 | 0.30x |
+
+Read that first two rows carefully. MiniLM buys a 5-point recall gain over
+keyword matching, and pays roughly 600x the indexing time for it. On this
+dataset that trade is hard to justify.
+
+The Turkish-specific model is a different story: +28 points over the baseline
+is a real jump, and worth the 3x slowdown against the other neural models.
+
+So the lesson is not "embeddings are overrated." It is: **a badly chosen
+embedding model is not better than keyword search, and nobody checks.**
+
+## Findings from the sample dataset
+
+**Documented configuration is not always the right configuration.** The e5
+model card specifies `query: ` and `passage: ` prefixes on input text. Applying
+them on this dataset *lowered* recall@5 from 0.750 to 0.692 and MRR from 0.792
+to 0.708 — same model, same data, same hardware.
+
+A plausible reason: these documents are short, five to eight words each, so an
+English prefix takes up a large share of every one of them. Whatever the cause,
+the recommended setting cost about six points here, and nothing short of
+measuring on your own data would have shown it.
+
+embedpick applies known prefixes by default, following the model authors'
+instructions, and `--no-presets` turns them off so you can check. Across 26
+queries the gap is worth roughly one and a half queries, so read the direction
+as suggestive rather than settled.
+
+**BM25 and embeddings fail on different queries.** On `ödeme yaparken sorun`
+("problem while paying") BM25 scored 1.00 and MiniLM scored 0.00. On
+`sahte ürün şüphesi` ("suspected counterfeit") it was the reverse. They are
+complementary, which is the empirical case for hybrid retrieval.
+
+**Small corpora hide everything.** On a 16-document pilot all three models
+scored 1.0 and looked identical. At 72 documents a 23-point spread appeared.
+A benchmark that cannot separate models tells you nothing about them.
+
+**Absolute timings are unreliable; ratios are not.** Across repeated runs on
+the same machine, `docs/sec` varied by up to 4x while the ratio between models
+stayed within about 20%. Report `rel_speed` when comparing across machines.
+
+## Install
+
+```bash
+git clone https://github.com/Mehmetalpertugtekin/embedpick.git
+cd embedpick
+python -m venv .venv
+.venv\Scripts\activate        # Windows
+source .venv/bin/activate     # macOS / Linux
+pip install -r requirements.txt
+```
+
+Python 3.9+.
+
+## Usage
+
+```bash
+# run with the bundled sample dataset
+python -m embedpick
+
+# your own data
+python -m embedpick --corpus my_docs.csv --queries my_queries.csv
+
+# pick models, evaluate top 10, show per-query detail
+python -m embedpick --models intfloat/multilingual-e5-base -k 10 --verbose
+
+# save the table
+python -m embedpick --out results.csv
+```
+
+`python -m embedpick --help` lists every flag.
+
+## Development
+
+```bash
+pip install -r requirements-dev.txt
+python -m pytest
+```
+
+Tests do not download any models, so they run in seconds. Make sure your
+virtual environment is active first — a missing `rank_bm25` in the test output
+usually means you installed into the system Python by mistake.
+
+## Data format
+
+**corpus.csv** — the documents to search over:
+
+```csv
+id,text
+1,Kargom hala elime ulaşmadı
+2,Sipariş takip numaram sistemde görünmüyor
+```
+
+**queries.csv** — queries and their correct answers:
+
+```csv
+query,relevant_ids
+kargo gecikmesi,1;5
+paketim nerede,1;2
+```
+
+Separate multiple correct answers with `;`. A query can have any number of
+them. Files must be UTF-8.
+
+Twenty to thirty queries is usually enough to see real differences. Include
+queries that share no words with their correct answer — those are the ones
+that test semantic matching rather than lucky keyword overlap.
+
+## Metrics
+
+**recall@k** — of the correct documents, what fraction appeared in the top k.
+Use this when you show the user a list of results.
+
+**MRR@k** — 1.0 if the first correct answer is at rank 1, 0.5 at rank 2, 0.33
+at rank 3, averaged over queries. Use this when you show one answer, or feed
+the top hit to an LLM.
+
+These can disagree, and the disagreement is informative. In an earlier run
+e5 had higher recall than MiniLM but lower MRR: it found more, but ranked
+worse. Which model is "better" depends on what you are building.
+
+**docs/sec** — indexing throughput. Machine-dependent, see the caveat above.
+
+**dim** and **index_mb** — vector width and index size. A 768-dimensional
+model needs twice the memory of a 384-dimensional one at the same corpus size.
+
+## Label checking
+
+Two things happen automatically:
+
+- If `relevant_ids` points at a document id that is not in the corpus, the run
+  stops and names the query. Otherwise that query silently scores zero forever
+  and you blame the model.
+- If *no* method — including BM25 — finds a query's answer, embedpick flags it.
+  When everything fails on the same query, the label is usually wrong. This
+  caught a mislabelled query during development.
+
+## Sample dataset
+
+`embedpick/sample_data/` contains 72 synthetic Turkish customer-support messages across nine
+themes (shipping, returns, payment, account, product quality, promotions,
+warranty, order management, support) and 26 labelled queries. It is written,
+not scraped, so it carries no licensing or privacy constraints.
+
+Several queries deliberately share no vocabulary with their answers — for
+example `güvenlik ihlali şüphesi` ("suspected security breach") maps to
+*"Hesabıma başkası girmiş olabilir"* ("someone else may have accessed my
+account"). Keyword search cannot solve these; that is the point.
+
+## Caveats
+
+- Timing on a 72-document corpus is close to measurement noise, particularly
+  for BM25. Treat the throughput column as indicative.
+- BM25 and neural encoders scale differently. The ratio at 72 documents is not
+  the ratio at 100,000.
+- Results are from one machine, CPU only, no GPU.
+
+## Roadmap
+
+- Hybrid retrieval (BM25 + embedding score fusion) as a fourth row
+- Hub detection: flag documents that surface for nearly every query
+- Markdown report export
+- Optional Gradio interface
+
+## License
+
+MIT

embedpick-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+embedpick/__init__.py,sha256=Ybzv5pEthoIrzGby5H69tBPsRknzd1BEzeGiFoBaOWE,258
+embedpick/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+embedpick/benchmark.py,sha256=uqh4T39jcjis86TeMkXCMkumjXx9GFRS2P3B_WGTAw4,3157
+embedpick/cli.py,sha256=RihVIlj2WWrwbqfdiQ_Bqw2ZTKHhWnnxVv6YBXt8RZo,3312
+embedpick/data.py,sha256=1pNyTzmngcADcRf8BGSvNW9wx0GHdQpiRx5MJMcPXCg,2183
+embedpick/metrics.py,sha256=T0S-8fs-lrl3Bef6txDpLQxyT6J2tUS8Rglz7rjfw1I,1676
+embedpick/retrievers.py,sha256=Xe30WabS75qPcCb16Re86D3d3T7o6fxLGyVf8gS5IzY,5004
+embedpick/sample_data/corpus.csv,sha256=Uqzp1qWWFvKPH4xLXFBCqIgrKe0fKKk08MKxy1AqSSI,3236
+embedpick/sample_data/queries.csv,sha256=XdyfiATgpvsMwmGuX2FijQhhqKnkfi_AloqcSyHNJAg,775
+embedpick-0.1.0.dist-info/licenses/LICENSE,sha256=TmjrxRWdTFitR2wsHBSyM7Jp4XH-PGzc7JMTmZj9-aM,1100
+embedpick-0.1.0.dist-info/METADATA,sha256=shJNskBoGeHmIxgcd2KSfVCDfIhQSxJ9e3yyujS-tMg,9261
+embedpick-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+embedpick-0.1.0.dist-info/entry_points.txt,sha256=OuhrM3J7vIydF3ZEHW-MmgCna4RTBQoVsiw0Z5WnZWw,49
+embedpick-0.1.0.dist-info/top_level.txt,sha256=QErZwZoHszm4YRgjfBVg0b-v8hKDQ55A_kIwjYXlhbs,10
+embedpick-0.1.0.dist-info/RECORD,,

embedpick-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

embedpick-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+embedpick = embedpick.cli:main

embedpick-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mehmet Alper Tuğtekin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

embedpick-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+embedpick