@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/embeddings-search/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: embeddings-search
+description: "Use when choosing an embedding model, chunk size, or query form, when semantic search returns irrelevant results, when adding hybrid BM25+vector or a reranker, or when a retrieval change needs a number (recall@k, nDCG, MRR). NOT operating the store — index tuning, quantization (that is `vector-db`) — nor the retrieve-to-answer loop (that is `rag`)."
+tags: [embeddings, semantic-search, chunking, hybrid-search, reranking, rrf, retrieval-eval, mteb, matryoshka]
+recommends: [vector-db, rag, structured-extraction, prompt-engineering, postgresdb]
+origin: ai-hub
+---
+
+# embeddings-search — make and judge the vectors
+
+You own the **embedding technique layer**: turn a corpus into searchable vectors, turn a
+question into a good retrieval, and **measure whether that retrieval is any good**. You stop the
+moment the right chunks come back, measured by a number. You do not assemble a prompt or
+generate an answer.
+
+Route the adjacent surfaces away:
+
+- **Operating the store** — collection schema, HNSW/IVFFlat tuning, metadata-filter path,
+  quantization, `ef_search` recall knobs → [`../vector-db/SKILL.md`](../vector-db/SKILL.md).
+  You decide *what vectors go in and how to query*; vector-db decides *how the store holds and
+  serves them*.
+- **The full retrieve → rerank → prompt → generate → answer loop** and its groundedness /
+  faithfulness eval → [`../rag/SKILL.md`](../rag/SKILL.md).
+- **Pulling typed fields out of documents** (invoice number, date, total) → [`../structured-extraction/SKILL.md`](../structured-extraction/SKILL.md).
+- **Writing the prompt the model reasons with** → [`../prompt-engineering/SKILL.md`](../prompt-engineering/SKILL.md).
+
+## 1. Pick the embedding model
+
+Decide on three axes: language coverage, quality tier (read MTEB but don't worship it), and
+cost — where cost is set by **dimensions**, because dims set storage and memory.
+
+| Model | Best when | Dims (Matryoshka) | Max input | ~Price /1M tok | Query/doc asymmetry |
+|---|---|---|---|---|---|
+| OpenAI `text-embedding-3-small` | Cheap English/multi baseline | 1536 (truncatable) | 8191 tok | ~$0.02 | none required |
+| OpenAI `text-embedding-3-large` | Higher quality, still API-simple | 3072 (truncatable) | 8191 tok | ~$0.13 | none required |
+| Cohere `embed-v4` | Strong multilingual, API | up to 1536 | long | API-priced | `search_query` vs `search_document` |
+| Voyage `voyage-3-large` | Retrieval-specialised, top tasks | model-set | long | API-priced | yes (`input_type`) |
+| Gemini Embedding | Tops MTEB English retrieval (~68.3) | truncatable | long | API-priced | yes (task type) |
+| `BGE-M3` / `e5` (open) | Self-host, no per-token bill | 1024 (BGE-M3) | long | self-host | yes (`query:` / `passage:`) |
+
+Quality anchor (mid-2026 MTEB English retrieval): Gemini ~68.3, Cohere `embed-v4` ~65.2,
+OpenAI `3-large` ~64.6, `BGE-M3` ~63.0. MTEB is the standard comparison, not a verdict on
+*your* domain — [`references/models.md`](references/models.md) carries the full model matrix
+(dims, max tokens, price, `input_type` convention, Matryoshka support) and how to read MTEB
+without over-trusting it.
+
+Two hard rules — each is a **silent** failure, no error, just worse results:
+
+- **Match the distance metric to the model.** A cosine-trained model indexed or queried with
+  L2 ranks silently wrong. Cosine → `<=>` in pgvector / `Distance.COSINE` in Qdrant. The index
+  operator itself is vector-db's job; the *requirement* originates from the model, so state it
+  in your config.
+- **Respect query/document asymmetry.** Cohere, Voyage, Gemini, e5, BGE expect a different
+  prompt or `input_type` for the query vs the stored passage. Embed both sides identically and
+  recall silently drops.
+
+**Dimensions = cost.** A 1024-dim float32 vector is 4 KB; at 10M docs that is 40 GB, and
+doubling dims doubles storage and memory. Matryoshka-trained models (OpenAI 3-*, Cohere,
+Gemini) let you **truncate** dims for graceful degradation — never re-embed the whole corpus
+just to shrink vectors.
+
+## 2. Chunk the corpus
+
+Start boring. Upgrade only when a number tells you to.
+
+```python
+# Default recipe: recursive split, TOKEN-accurate count, 10–20% overlap.
+import tiktoken
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+
+enc = tiktoken.get_encoding("cl100k_base")
+splitter = RecursiveCharacterTextSplitter.from_tiktoken_encoder(
+    encoding_name="cl100k_base",
+    chunk_size=512,      # tokens, not characters
+    chunk_overlap=64,    # ~12% — keeps sentences from being cut mid-thought
+)
+chunks = splitter.split_text(document_text)
+```
+
+Counting by characters instead of tokens is the most common own-goal: 512 characters is
+~100–130 tokens of English and far fewer of CJK, so "512" silently means different things per
+language and per model limit.
+
+Upgrade ladder — graduate only when retrieval metrics (section 6) justify the added compute:
+
+| Strategy | When it pays | Cost |
+|---|---|---|
+| Recursive (default) | Always start here | lowest |
+| Semantic (group by meaning) | Topic-mixed pages where fixed splits cut mid-idea; ~70% lift over naive in some benchmarks | one extra embed pass |
+| Late chunking | Docs heavy with pronouns/anaphora ("it", "the company"); +10–12% on those | needs a long-context model |
+| Contextual retrieval (prepend a heading/summary per chunk) | Chunks that aren't self-contained without their section | higher compute, more tokens stored |
+
+**Embed the searchable text; store the rest as metadata.** What you embed is what gets matched
+— don't bury the answer text under boilerplate, and don't embed raw HTML.
+
+## 3. Construct the query
+
+The query is half the retrieval. Embed it the way the model expects, then improve it only when
+recall data says you should.
+
+```python
+# Asymmetric model: query and document use DIFFERENT input_type. Getting this wrong is silent.
+q_vec   = embed(text=user_question, input_type="search_query")     # Cohere / Voyage
+d_vec   = embed(text=passage,       input_type="search_document")
+# e5 / BGE convention is a textual prefix instead:
+#   query    -> "query: how do refunds work"
+#   passage  -> "passage: Refunds are processed within 14 days…"
+```
+
+Query-side techniques, when each pays:
+
+- **Query rewriting** — when user queries are terse or full of pronouns; normalise before
+  embedding.
+- **HyDE** (embed a hypothetical answer, not the question) — when questions are short and
+  answers are long/technical, so the answer-shaped vector lands nearer the passage.
+- **Multi-query** (fan out 3–4 paraphrases, union the hits) — when one phrasing under-recalls;
+  costs N embeds and a dedup.
+
+## 4. Hybrid + rerank
+
+Dense and sparse fail in complementary ways: **BM25 nails exact terms, IDs, SKUs, rare
+tokens**; **dense nails paraphrase**. That is why exact-match queries return nothing while
+paraphrases work — the fix is adding sparse, not a bigger embedding model.
+
+Fuse by **rank, not score**, with Reciprocal Rank Fusion so you never have to calibrate BM25
+tf-idf magnitudes against cosine magnitudes per corpus:
+
+```python
+# RRF: each doc scores 1/(k + rank) summed across the dense and sparse lists. k≈60.
+def rrf(*ranked_lists, k=60):
+    scores = {}
+    for lst in ranked_lists:                 # fan-in 20–100 per list
+        for rank, doc_id in enumerate(lst):  # rank is 0-based
+            scores[doc_id] = scores.get(doc_id, 0) + 1.0 / (k + rank + 1)
+    return sorted(scores, key=scores.get, reverse=True)
+```
+
+Then a **cross-encoder reranker** sits AFTER fusion: take top-50, score each against the
+original query, keep top-5 for downstream use.
+
+- Current models: Cohere `rerank-v4.0-pro` / `rerank-v4.0-fast` (note `rerank-3.5` is
+  deprecated). Voyage `rerank-2.5` (2025-08-11) is the first widely available
+  **instruction-following** reranker — 32K-token context (8× Cohere v3.5), reports +7.94%
+  accuracy vs Cohere v3.5 on a 93-dataset suite.
+- **A reranker raises precision but cannot recover a doc the retriever never returned.** Recall
+  is upstream. If the right chunk isn't in the top-50, no reranker saves you — fix recall first.
+
+The fusion and index *mechanics per engine* (how Qdrant/Weaviate/pgvector run hybrid) are
+vector-db's: [`../vector-db/SKILL.md`](../vector-db/SKILL.md).
+
+## 5. Measure retrieval quality
+
+This is the rigor of the skill. "Search is bad" is not actionable; "recall@10 is 0.62" is.
+
+1. **Build a golden query set** — 30–50+ labeled `query → relevant doc ids` pairs drawn from
+   real questions. This is the asset; everything else is reproducible from it.
+2. **Pick metrics** — definitions, a runnable Python eval skeleton, golden-set construction and
+   the A/B-one-change methodology are in
+   [`references/evaluation.md`](references/evaluation.md):
+   - **recall@k** — of the truly relevant docs, how many landed in the top-k. Catches "the
+     right chunk never came back."
+   - **nDCG@k** — rewards relevant docs ranked higher. Catches "right docs, wrong order."
+   - **MRR** — how high the *first* relevant doc sits. Catches "the one answer is buried."
+3. **Move-the-number loop.** Establish a baseline, **change exactly one thing** (model OR chunk
+   size OR fusion OR reranker), re-measure on the **same** query set. Two changes at once and
+   you learn nothing.
+
+A retrieval change shipped without a before/after number on a golden set is a guess. `verify.sh`
+flags hybrid/rerank artifacts that mention no recall/nDCG/MRR for exactly this reason.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| Chunk size in characters | "512" means a different token count per language/model | Token-accurate count (`tiktoken`/model tokenizer) |
+| Same `input_type` for query and document | Asymmetric models silently lose recall, no error | `search_query` vs `search_document` (or `query:`/`passage:`) |
+| Cosine model indexed/queried with L2 | Ranking is silently wrong | Match metric to model (cosine → `<=>`) |
+| Add a reranker to fix bad recall | Reranker only reorders what retrieval returned | Fix recall (hybrid, chunking, model) first |
+| No overlap on prose | Sentences cut mid-thought lose the answer | 10–20% overlap |
+| Tuning by eyeballing one query | One query isn't a measurement | Golden set + recall@k/nDCG before vs after |
+| Trusting MTEB rank for your domain | Leaderboard ≠ your corpus/language | Eval the top 2–3 on your own golden set |
+| Over-large dims "for safety" | Doubles storage/RAM, little recall gain | Right-size; truncate via Matryoshka |
+| Re-embedding the corpus to change dims | Wasteful when the model is Matryoshka-trained | Truncate dims, don't re-embed |
+| Embedding raw HTML/boilerplate | Match signal drowns in markup | Embed clean text; keep the rest as metadata |

package/skills/shared/embeddings-search/evals/README.md

@@ -0,0 +1,10 @@
+# Evals — embeddings-search
+
+These cases are routing and capability checks for a human or an LLM grader, not an automated
+test suite. To run them: read each `should_trigger` prompt and confirm an agent would reach for
+`embeddings-search`; read each `should_not_trigger` prompt and confirm it routes to the named
+sibling (`vector-db`, `rag`, `structured-extraction`, `prompt-engineering`) for the stated
+reason; then grade the `capability` scenario by checking the produced answer against every item
+in its `must_include` rubric. A pass covers all routing cases plus full rubric coverage on the
+capability scenario. The separate `scripts/verify.sh` lints produced embedding/eval artifacts
+and is independent of these cases.

package/skills/shared/embeddings-search/evals/cases.yaml

@@ -0,0 +1,44 @@
+skill: embeddings-search
+
+should_trigger:
+  - prompt: "Which embedding model and chunk size should I use for these PDFs?"
+    why: "The core model + chunking decision this skill owns; no store or pipeline named."
+  - prompt: "My semantic search returns irrelevant results, how do I make retrieval better?"
+    why: "Relevance-quality symptom at the technique layer — model/chunking/hybrid/rerank, not store ops."
+  - prompt: "How do I measure if my retrieval is actually good — recall@k or nDCG?"
+    why: "Retrieval-quality measurement (golden set, recall/nDCG/MRR) is explicitly owned here."
+  - prompt: "Add a reranker and hybrid BM25+vector scoring to lift relevance."
+    why: "Hybrid fusion + reranker stage is a named section of this skill."
+  - prompt: "Exact-match queries like product SKUs return nothing but paraphrases work fine."
+    why: "Non-obvious: never names embeddings, but the diagnosis is a dense-only blind spot fixed by adding sparse/BM25 — squarely this skill."
+  - prompt: "recall@10 is fine but the top result is the wrong document, why?"
+    why: "Non-obvious ordering symptom — points at nDCG/MRR and a reranker, both owned here, not a store problem."
+  - prompt: "quin model d'embeddings i quina mida de chunk faig servir per a aquests documents legals"
+    why: "Catalan trigger on the model + chunk-size choice, the skill's primary decision."
+
+should_not_trigger:
+  - prompt: "Set up a Qdrant collection with HNSW and a metadata filter."
+    route_to: vector-db
+    why: "Collection schema and index/filter path are store operation, not embedding technique."
+  - prompt: "Build the full RAG pipeline: retrieve, prompt, and generate the grounded answer."
+    route_to: rag
+    why: "End-to-end answer loop plus groundedness eval is beyond where this skill stops (chunks returned)."
+  - prompt: "Pull the invoice number, date, and total out of these PDFs into JSON."
+    route_to: structured-extraction
+    why: "Typed field extraction from documents, not search/retrieval."
+  - prompt: "My Postgres <=> query is slow and returns fewer than k rows with a WHERE filter."
+    route_to: vector-db
+    why: "pgvector iterative-scan / index issue lives in the store layer."
+  - prompt: "Write a better system prompt so the model stops hallucinating tools."
+    route_to: prompt-engineering
+    why: "Prompt design, not retrieval quality."
+
+capability:
+  - scenario: "Semantic search over 50k multilingual support articles returns irrelevant results. The user doesn't know which embedding model or chunk size to use and has no way to tell whether a change helps."
+    must_include:
+      - "Picks a multilingual-capable model and justifies dims/cost, noting Matryoshka truncation as the lever instead of re-embedding"
+      - "Matches the distance metric to the model and embeds query vs document with the correct input_type asymmetry"
+      - "Gives a concrete chunking default (recursive ~512-token, token-accurate count, 10–20% overlap) and names when to upgrade (semantic/late/contextual) gated on metrics"
+      - "Adds hybrid dense+sparse fused by RRF (1/(k+rank), k≈60), then a reranker top-50→top-5, with the rule that a reranker cannot recover missed recall"
+      - "Builds a labeled golden query set and measures recall@k / nDCG@k (and MRR) before and after, changing exactly one variable"
+      - "Routes store/index setup to vector-db and the full answer/generation loop to rag"

package/skills/shared/embeddings-search/references/evaluation.md

@@ -0,0 +1,86 @@
+# Retrieval evaluation
+
+Turn "search is bad" into a number you can move. Everything here runs offline against a labeled
+query set — no LLM judge, no network.
+
+## 1. Build the golden query set
+
+The golden set is the asset. Aim for **30–50+** entries; more is better. Each entry is a real
+question plus the doc ids that genuinely answer it.
+
+```json
+[
+  {"query": "how long do refunds take", "relevant": ["doc_412", "doc_77"]},
+  {"query": "SKU AB-9931 specs",        "relevant": ["doc_1290"]},
+  {"query": "puc cancel·lar la subscripció?", "relevant": ["doc_88", "doc_640"]}
+]
+```
+
+Sourcing tips:
+- Pull real queries from logs; don't invent only easy ones — include the exact-match and the
+  multilingual cases that break dense-only retrieval.
+- Label relevance against the **chunk/doc id your retriever returns**, not the source PDF.
+- Keep it in version control. A change to the set invalidates old numbers.
+
+## 2. Metrics — what each one catches
+
+- **recall@k**: fraction of an entry's relevant docs found in the top-k. Catches *the right
+  chunk never came back* (a recall problem no reranker can fix).
+- **nDCG@k**: discounted gain that rewards relevant docs ranked higher (uses `log2(rank+1)`
+  discount). Catches *right docs, wrong order*.
+- **MRR**: mean of `1/rank` of the first relevant doc. Catches *the one answer is buried deep*.
+
+## 3. Runnable skeleton
+
+```python
+import math
+
+def recall_at_k(retrieved, relevant, k):
+    top = set(retrieved[:k])
+    rel = set(relevant)
+    return len(top & rel) / len(rel) if rel else 0.0
+
+def ndcg_at_k(retrieved, relevant, k):
+    rel = set(relevant)
+    dcg = sum(1.0 / math.log2(i + 2) for i, d in enumerate(retrieved[:k]) if d in rel)
+    ideal = sum(1.0 / math.log2(i + 2) for i in range(min(len(rel), k)))
+    return dcg / ideal if ideal else 0.0
+
+def mrr(retrieved, relevant):
+    rel = set(relevant)
+    for i, d in enumerate(retrieved):
+        if d in rel:
+            return 1.0 / (i + 1)
+    return 0.0
+
+def evaluate(golden, search_fn, k=10):
+    rs, ns, ms = [], [], []
+    for row in golden:
+        got = search_fn(row["query"])          # -> ordered list of doc ids
+        rs.append(recall_at_k(got, row["relevant"], k))
+        ns.append(ndcg_at_k(got, row["relevant"], k))
+        ms.append(mrr(got, row["relevant"]))
+    n = len(golden)
+    return {
+        f"recall@{k}": sum(rs) / n,
+        f"ndcg@{k}":   sum(ns) / n,
+        "mrr":         sum(ms) / n,
+    }
+```
+
+## 4. A/B one change at a time
+
+```text
+baseline   = evaluate(golden, search_v0)        # record it
+candidate  = evaluate(golden, search_v1)         # changed ONE thing
+# compare on the SAME golden set; keep the change only if the metric you care about went up
+```
+
+Change exactly one variable per run: the embedding model, OR the chunk size/strategy, OR the
+fusion (`k` in RRF, fan-in), OR the reranker. Stacking changes means you can't attribute the
+delta — and a regression hides inside an improvement.
+
+Typical decision pattern:
+- recall@k low → upstream: model choice, chunking, add sparse/hybrid. A reranker won't help.
+- recall@k high but nDCG/MRR low → ordering: add or tune the reranker.
+- exact-term queries failing while paraphrases pass → add BM25/sparse and re-measure.

package/skills/shared/embeddings-search/references/models.md

@@ -0,0 +1,73 @@
+# Embedding model matrix (mid-2026)
+
+Read this to pick a model, size its dimensions, and call it with the right `input_type`. Facts
+dated 2026-06-02; re-check provider docs before committing a corpus, since model names and
+prices move.
+
+## Matrix
+
+| Model | Provider | Dims | Matryoshka truncation | Max input | ~Price /1M tok | Query/doc convention |
+|---|---|---|---|---|---|---|
+| `text-embedding-3-small` | OpenAI | 1536 | yes (`dimensions` param) | 8191 tok | ~$0.02 | symmetric (no input_type) |
+| `text-embedding-3-large` | OpenAI | 3072 | yes (`dimensions` param) | 8191 tok | ~$0.13 | symmetric |
+| `embed-v4` | Cohere | up to 1536 | yes | long | API-priced | `input_type=search_query` / `search_document` |
+| `voyage-3-large` | Voyage | model-set | partial | long | API-priced | `input_type="query"` / `"document"` |
+| Gemini Embedding | Google | truncatable | yes | long | API-priced | task type (retrieval query vs document) |
+| `BGE-M3` | open (self-host) | 1024 | no | 8192 tok | infra-only | prefix `query:` / `passage:` |
+| `e5-large` family | open (self-host) | 1024 | no | 512 tok | infra-only | prefix `query:` / `passage:` |
+
+MTEB English-retrieval anchors at the time of writing: Gemini ~68.3, Cohere `embed-v4` ~65.2,
+OpenAI `text-embedding-3-large` ~64.6, `BGE-M3` ~63.0. Voyage models lead retrieval-specific
+task slices.
+
+## How to read MTEB without over-trusting it
+
+- MTEB is an **average across many tasks and domains**. A model two points higher on the
+  overall board can be worse on legal Catalan, code, or your support tickets.
+- The board is **English-weighted**. For multilingual corpora, weight the multilingual slice
+  and confirm your languages are actually covered.
+- Leaderboards get **gamed and contaminated** over time. Treat the top 3–4 as a shortlist, then
+  run your own golden-set eval (see `evaluation.md`) — that number is the only one that decides.
+
+## input_type asymmetry — the silent recall killer
+
+Asymmetric models were trained so the query vector and the passage vector live in compatible
+but differently-prompted spaces. Embedding both sides the same way produces no error and
+quietly worse recall.
+
+```python
+# Cohere
+co.embed(texts=[q], model="embed-v4", input_type="search_query")
+co.embed(texts=[d], model="embed-v4", input_type="search_document")
+
+# Voyage
+vo.embed([q], model="voyage-3-large", input_type="query")
+vo.embed([d], model="voyage-3-large", input_type="document")
+
+# e5 / BGE — textual prefix
+embed("query: " + q)
+embed("passage: " + d)
+
+# OpenAI 3-* — symmetric, no input_type needed
+client.embeddings.create(model="text-embedding-3-small", input=[q])
+```
+
+## Matryoshka: shrink without re-embedding
+
+Matryoshka-trained models pack the most important signal in the leading dimensions, so you can
+slice a vector and keep most of the quality.
+
+```python
+# Ask for fewer dims at embed time…
+client.embeddings.create(model="text-embedding-3-large", input=[d], dimensions=1024)
+# …or truncate + re-normalise an already-stored full vector:
+import numpy as np
+def truncate(vec, n):
+    v = np.asarray(vec[:n], dtype="float32")
+    return (v / np.linalg.norm(v)).tolist()
+```
+
+Storage math: a float32 dim costs 4 bytes. 3072 dims = 12 KB/vector; 1024 dims = 4 KB. At 10M
+docs that is the difference between ~120 GB and ~40 GB. Cut dims first, measure recall on the
+golden set, and only keep the cut if recall holds. Do **not** re-embed the corpus from scratch
+just to change dimension count when the model is Matryoshka-trained.

package/skills/shared/embeddings-search/scripts/verify.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — embeddings-search skill gate. A HEURISTIC config/eval linter, not a live check.
+#
+# Usage:  scripts/verify.sh [FILE ...]
+#   FILE = a produced artifact (embedding/ingest config, query code, eval harness). With no
+#   args it scans the current directory for *.py / *.json / *.yaml / *.yml / *.md artifacts
+#   that mention an embedding model, chunking, input_type, RRF/rerank, or a retrieval metric.
+#   Read-only; never connects to anything; never writes.
+#
+# Exit code: non-zero ONLY on a hard, unambiguous violation:
+#   - a cosine-style embedding model named alongside an L2-only metric, no cosine metric anywhere;
+#   - an asymmetric provider named but query and document embedded with the SAME input_type.
+# Advisory notes (exit 0): hybrid/rerank with no recall/nDCG/MRR/golden-set mention; chunk size
+# declared with no overlap and no token-accurate counting. An empty or clean target exits 0.
+#
+# Portable to stock macOS bash 3.2: no mapfile, no associative arrays, arrays pre-initialised.
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+note() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+# ---- collect target files -------------------------------------------------
+FILES=()
+if [ "$#" -gt 0 ]; then
+  for f in "$@"; do
+    [ -f "$f" ] && FILES+=("$f") || note "not a file, skipping: $f"
+  done
+else
+  ROOT="$(pwd)"
+  while IFS= read -r -d '' f; do
+    FILES+=("$f")
+  done < <(
+    find "$ROOT" \
+      \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/vendor/*' -o -path '*/.venv/*' \) -prune -o \
+      -type f \( -name '*.py' -o -name '*.json' -o -name '*.yaml' -o -name '*.yml' -o -name '*.md' \) -print0 2>/dev/null
+  )
+fi
+
+if [ "${#FILES[@]}" -eq 0 ]; then
+  ok "no artifacts to check — clean"
+  exit 0
+fi
+
+# Keep only files that look like an embeddings/retrieval artifact, so a generic repo scan stays
+# quiet. A clean (non-matching) set still exits 0.
+TARGETS=()
+for f in "${FILES[@]}"; do
+  if grep -Eiq 'text-embedding-3|embed-v4|voyage-|bge-|e5-|gemini.?embedding|input_type|chunk_size|chunk_overlap|rerank|rrf|reciprocal.?rank|recall@|ndcg|mrr|embeddings\.create|\.embed\(' "$f" 2>/dev/null; then
+    TARGETS+=("$f")
+  fi
+done
+
+if [ "${#TARGETS[@]}" -eq 0 ]; then
+  ok "no embeddings/retrieval artifacts detected — nothing to lint"
+  exit 0
+fi
+
+# ---- per-file heuristics --------------------------------------------------
+for f in "${TARGETS[@]}"; do
+  printf -- '--- %s\n' "$f"
+
+  # 1) Metric mismatch: a cosine-style model but only L2 ops named, no cosine anywhere.
+  mentions_cosine_model=$(grep -Eic 'text-embedding-3|cohere|embed-v4|voyage-|bge-|e5-|gemini.?embedding|sentence-transformers|all-minilm|normaliz' "$f" 2>/dev/null || true)
+  has_cosine=$(grep -Eic '<=>|cosine|vector_cosine_ops|distance\.cosine' "$f" 2>/dev/null || true)
+  has_l2=$(grep -Eic '<->|vector_l2_ops|euclidean|distance\.euclid|metric *= *.?l2' "$f" 2>/dev/null || true)
+  if [ "$mentions_cosine_model" -gt 0 ] && [ "$has_l2" -gt 0 ] && [ "$has_cosine" -eq 0 ]; then
+    err "metric mismatch: names a cosine-style embedding model but only L2 distance — ranking is silently wrong. Use cosine (<=> / vector_cosine_ops)."
+  fi
+
+  # 2) Asymmetric provider named but query+document use the SAME input_type. Conservative:
+  #    only flag when an asymmetric provider is named.
+  names_asym=$(grep -Eic 'cohere|embed-v4|voyage-|bge-|e5-|gemini.?embedding' "$f" 2>/dev/null || true)
+  sq=$(grep -Eic 'input_type *= *.?(search_query|query)|"query: ' "$f" 2>/dev/null || true)
+  sd=$(grep -Eic 'input_type *= *.?(search_document|document|passage)|"passage: ' "$f" 2>/dev/null || true)
+  any_input_type=$(grep -Eic 'input_type *=|"query: |"passage: ' "$f" 2>/dev/null || true)
+  if [ "$names_asym" -gt 0 ] && [ "$any_input_type" -gt 0 ] && [ "$sd" -eq 0 ] && [ "$sq" -gt 0 ]; then
+    err "asymmetric model uses the query input_type for both sides (no document/passage type found) — recall silently drops. Embed documents with the document/passage input_type."
+  fi
+
+  # 3) Hybrid / rerank present but no retrieval-quality metric mentioned (advisory).
+  has_hybrid=$(grep -Eic 'rerank|rrf|reciprocal.?rank|bm25|hybrid' "$f" 2>/dev/null || true)
+  has_metric=$(grep -Eic 'recall@|recall_at|ndcg|mrr|golden|relevant' "$f" 2>/dev/null || true)
+  if [ "$has_hybrid" -gt 0 ] && [ "$has_metric" -eq 0 ]; then
+    note "hybrid/rerank present but no recall/nDCG/MRR or golden-set mention — measure relevance before vs after on a fixed query set."
+  fi
+
+  # 4) Chunk size declared with no overlap and no token-accurate counting (advisory).
+  has_chunk_size=$(grep -Eic 'chunk_size' "$f" 2>/dev/null || true)
+  has_overlap=$(grep -Eic 'chunk_overlap|overlap' "$f" 2>/dev/null || true)
+  has_token_count=$(grep -Eic 'tiktoken|tokenizer|encoding_name|token.?accurate|from_tiktoken' "$f" 2>/dev/null || true)
+  if [ "$has_chunk_size" -gt 0 ] && [ "$has_overlap" -eq 0 ] && [ "$has_token_count" -eq 0 ]; then
+    note "chunk_size declared with no overlap and no token-accurate counting — add 10–20% overlap and count tokens (tiktoken/tokenizer), not characters."
+  fi
+done
+
+if [ "$EXIT" -eq 0 ]; then
+  ok "no hard violations"
+fi
+exit "$EXIT"