embedpick 0.1.0__tar.gz

embedpick-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,202 @@
+# 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/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-0.1.0/embedpick/__main__.py

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

embedpick-0.1.0/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-0.1.0/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())