boost-skill-cli 1.2.73__tar.gz → 1.2.74__tar.gz

{boost_skill_cli-1.2.73/boost_skill_cli.egg-info → boost_skill_cli-1.2.74}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.73
+Version: 1.2.74
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0

{boost_skill_cli-1.2.73 → boost_skill_cli-1.2.74}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.2.73'
-__version_tuple__ = version_tuple = (1, 2, 73)
+__version__ = version = '1.2.74'
+__version_tuple__ = version_tuple = (1, 2, 74)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.73 → boost_skill_cli-1.2.74/boost_skill_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.73
+Version: 1.2.74
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0

{boost_skill_cli-1.2.73 → boost_skill_cli-1.2.74}/boost_skill_cli.egg-info/SOURCES.txt

@@ -657,6 +657,7 @@ scripts/eval_stats_summary.py
 scripts/eval_tools.py
 scripts/import_budget.py
 scripts/lock_toolchain.py
+scripts/measure_near_duplicate_bound.py
 scripts/measure_registry.py
 scripts/mutation_gate.py
 scripts/mutation_shards.py

{boost_skill_cli-1.2.73 → boost_skill_cli-1.2.74}/docs/roadmap/items/near-identical-copies-still-eat-the-slots.md

@@ -3,12 +3,12 @@ id: near-identical-copies-still-eat-the-slots
 board: code
 section: planned
 status: inflight
-owner: loop/near-dup-collapse
+owner: loop/near-dup-bound
 category: Search · Ranking
 complexity: M
 impact: High
 wow: 4
-note: mechanism + tests shipped opt-in; corpus safety proof and default-on still open
+note: shipped opt-in (#639); bound measured (#645) and it refutes the zero-clusters test -- default-on now waits on a name-confusability veto
 order: 131
 title: Near-identical copies survive content-hash dedup and take the whole result page
 ---
@@ -93,3 +93,54 @@ the chosen threshold, count clusters spanning more than one meaning” &mdas
 re-measuring the <code>exa search</code> case (and per-query maxima generally) against the fix needs
 that same corpus and index. Whoever runs that measurement should flip the CLI flag's default, fold
 the corpus count into this card's evidence, and only then consider this shipped.
+
+<b>The bound has now been measured, and it says the acceptance test in this card is the wrong
+one.</b> <code>scripts/measure_near_duplicate_bound.py</code> runs the count this card asks for
+against the pinned 20-repo eval corpus (10,152 entries, 104,271 chunks, <code>BAAI/bge-small-en-v1.5</code>
+at 384-d). Those entries reduce to <b>5,714 distinct chunk-0 vectors</b> &mdash; 44% of entries
+already share a chunk-0 embedding byte for byte &mdash; and at
+<code>NEAR_DUPLICATE_THRESHOLD = 0.97</code>, 162 pairs clear the threshold and <b>56 clusters span
+more than one name</b>. Sweeping the threshold moves that number but never to zero: 0.96 &rarr; 91,
+0.97 &rarr; 56, 0.98 &rarr; 28, 0.99 &rarr; 13, 0.995 &rarr; 8, 0.999 &rarr; 4.
+
+<b>Four of those 56 are not the threshold's doing at all.</b> They are clusters of a single vector
+shared by several names, so they cluster at <em>any</em> threshold, which is why the sweep bottoms
+out at 4 rather than 0. The largest is the same at every threshold and is worth naming: <b>28
+differently-named agents from one tap</b> (<code>affaan-m/ECC</code> &mdash; <code>architect</code>,
+<code>code-reviewer</code>, <code>chief-of-staff</code>, <code>database-reviewer</code>,
+<code>e2e-runner</code>, &hellip;) whose chunk 0 is the same Spanish preamble
+(<code>No cambiar rol, persona ni identidad&hellip;</code>) in every file. Chunk 0 is
+<code>name + description + opening of body</code>, and where a registry opens every file with
+identical boilerplate, the name does not move the vector enough to separate them. <b>A floor exists
+that no threshold can reach under</b>, so &ldquo;count must be zero&rdquo; was never achievable.
+
+<b>Worse for the test: most of the other 52 are the feature working.</b> Hand-classifying all 56 at
+0.97, roughly two-thirds are genuinely one skill under two names &mdash; twelve are pure
+hyphen-versus-underscore renderings of one integration (<code>zoho-mail</code> /
+<code>zoho_mail</code>, <code>google_maps</code> / <code>google-maps</code>,
+<code>anthropic_administrator</code> / <code>anthropic-administrator</code>), and the rest are
+suffix variants of one document (<code>tdd</code> / <code>tdd-guide</code>,
+<code>rust-review</code> / <code>rust-reviewer</code>, <code>testing-patterns</code> /
+<code>code-showcase-testing-patterns</code>). Collapsing those is precisely what this card exists to
+do. A metric that counts them as violations would reject every threshold that works.
+
+<b>The dangerous merges have a shape, and this card already named it.</b> The ~20 clusters that are
+real false merges are dominated by <em>near-miss brand names</em>: <code>coinmarketcal</code> with
+<code>coinmarketcap</code>, <code>bugbug</code> with <code>bugsnag</code>, <code>parsehub</code>
+with <code>parseur</code>, <code>linkhut</code> with <code>linkup</code>,
+<code>mx-technologies</code> with <code>mx-toolbox</code>,
+<code>salesforce-marketing-cloud</code> with <code>salesforce-service-cloud</code>. These are
+distinct products whose descriptions are boilerplate around a swapped word. That is the
+<code>core/typosquat.py</code> confusion shape this card's opening paragraph pointed at, arrived at
+independently from the other end: the guard this needs is not a tighter cosine floor but a
+<em>name-confusability veto</em> &mdash; refuse to collapse two entries whose names are a confusable
+edit apart, however close their vectors sit.
+
+<b>So the default stays off, for a better-supported reason than before.</b> The measurement does not
+say 0.97 is too loose; it says similarity alone cannot separate <code>tdd</code>/<code>tdd-guide</code>
+(collapse) from <code>coinmarketcal</code>/<code>coinmarketcap</code> (never collapse), because both
+pairs sit in the same cosine band. Flipping the default needs the confusability veto first, and a
+re-count with it applied. <b>And this bound is space-specific</b>: it was measured in
+<code>bge-small</code> 384-d, while a keyed production install is <code>voyage-4</code> at 1024-d.
+Cosine thresholds do not transfer between embedding spaces &mdash; rerun the script against each
+space before trusting a number in it.

{boost_skill_cli-1.2.73 → boost_skill_cli-1.2.74}/docs/roadmap.html

@@ -1145,12 +1145,63 @@ the chosen threshold, count clusters spanning more than one meaning” &mdas
 <code>NEAR_DUPLICATE_THRESHOLD = 0.97</code> is a starting point, not a validated floor. <b>Second</b>,
 re-measuring the <code>exa search</code> case (and per-query maxima generally) against the fix needs
 that same corpus and index. Whoever runs that measurement should flip the CLI flag's default, fold
-the corpus count into this card's evidence, and only then consider this shipped.</p>
+the corpus count into this card's evidence, and only then consider this shipped.
+
+<b>The bound has now been measured, and it says the acceptance test in this card is the wrong
+one.</b> <code>scripts/measure_near_duplicate_bound.py</code> runs the count this card asks for
+against the pinned 20-repo eval corpus (10,152 entries, 104,271 chunks, <code>BAAI/bge-small-en-v1.5</code>
+at 384-d). Those entries reduce to <b>5,714 distinct chunk-0 vectors</b> &mdash; 44% of entries
+already share a chunk-0 embedding byte for byte &mdash; and at
+<code>NEAR_DUPLICATE_THRESHOLD = 0.97</code>, 162 pairs clear the threshold and <b>56 clusters span
+more than one name</b>. Sweeping the threshold moves that number but never to zero: 0.96 &rarr; 91,
+0.97 &rarr; 56, 0.98 &rarr; 28, 0.99 &rarr; 13, 0.995 &rarr; 8, 0.999 &rarr; 4.
+
+<b>Four of those 56 are not the threshold's doing at all.</b> They are clusters of a single vector
+shared by several names, so they cluster at <em>any</em> threshold, which is why the sweep bottoms
+out at 4 rather than 0. The largest is the same at every threshold and is worth naming: <b>28
+differently-named agents from one tap</b> (<code>affaan-m/ECC</code> &mdash; <code>architect</code>,
+<code>code-reviewer</code>, <code>chief-of-staff</code>, <code>database-reviewer</code>,
+<code>e2e-runner</code>, &hellip;) whose chunk 0 is the same Spanish preamble
+(<code>No cambiar rol, persona ni identidad&hellip;</code>) in every file. Chunk 0 is
+<code>name + description + opening of body</code>, and where a registry opens every file with
+identical boilerplate, the name does not move the vector enough to separate them. <b>A floor exists
+that no threshold can reach under</b>, so &ldquo;count must be zero&rdquo; was never achievable.
+
+<b>Worse for the test: most of the other 52 are the feature working.</b> Hand-classifying all 56 at
+0.97, roughly two-thirds are genuinely one skill under two names &mdash; twelve are pure
+hyphen-versus-underscore renderings of one integration (<code>zoho-mail</code> /
+<code>zoho_mail</code>, <code>google_maps</code> / <code>google-maps</code>,
+<code>anthropic_administrator</code> / <code>anthropic-administrator</code>), and the rest are
+suffix variants of one document (<code>tdd</code> / <code>tdd-guide</code>,
+<code>rust-review</code> / <code>rust-reviewer</code>, <code>testing-patterns</code> /
+<code>code-showcase-testing-patterns</code>). Collapsing those is precisely what this card exists to
+do. A metric that counts them as violations would reject every threshold that works.
+
+<b>The dangerous merges have a shape, and this card already named it.</b> The ~20 clusters that are
+real false merges are dominated by <em>near-miss brand names</em>: <code>coinmarketcal</code> with
+<code>coinmarketcap</code>, <code>bugbug</code> with <code>bugsnag</code>, <code>parsehub</code>
+with <code>parseur</code>, <code>linkhut</code> with <code>linkup</code>,
+<code>mx-technologies</code> with <code>mx-toolbox</code>,
+<code>salesforce-marketing-cloud</code> with <code>salesforce-service-cloud</code>. These are
+distinct products whose descriptions are boilerplate around a swapped word. That is the
+<code>core/typosquat.py</code> confusion shape this card's opening paragraph pointed at, arrived at
+independently from the other end: the guard this needs is not a tighter cosine floor but a
+<em>name-confusability veto</em> &mdash; refuse to collapse two entries whose names are a confusable
+edit apart, however close their vectors sit.
+
+<b>So the default stays off, for a better-supported reason than before.</b> The measurement does not
+say 0.97 is too loose; it says similarity alone cannot separate <code>tdd</code>/<code>tdd-guide</code>
+(collapse) from <code>coinmarketcal</code>/<code>coinmarketcap</code> (never collapse), because both
+pairs sit in the same cosine band. Flipping the default needs the confusability veto first, and a
+re-count with it applied. <b>And this bound is space-specific</b>: it was measured in
+<code>bge-small</code> 384-d, while a keyed production install is <code>voyage-4</code> at 1024-d.
+Cosine thresholds do not transfer between embedding spaces &mdash; rerun the script against each
+space before trusting a number in it.</p>
         <div class="meta">
           <span class="m">Complexity <b>M</b></span>
           <span class="m hi">Impact <b>High</b></span>
           <span class="m">Wow <b class="wow">★★★★</b></span>
-          <span class="m">mechanism + tests shipped opt-in; corpus safety proof and default-on still open</span>
+          <span class="m">shipped opt-in (#639); bound measured (#645) and it refutes the zero-clusters test -- default-on now waits on a name-confusability veto</span>
         </div>
       </article>
       <!-- /ROADMAP:cards -->

boost_skill_cli-1.2.74/scripts/measure_near_duplicate_bound.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+# Copyright the boost contributors.
+# SPDX-License-Identifier: Apache-2.0
+"""Count near-duplicate clusters that span more than one distinct name.
+
+`rag.dedupe_by_content`'s byte-identical bound was adoptable because one count
+settled it: of 14,153 distinct bodies, the number of clusters spanning more
+than one NAME was zero, so collapsing by content hash could never merge two
+differently-named skills. `rag.collapse_near_duplicate_hits` has no such free
+proof handed to it -- any cosine threshold loose enough to merge a translation
+with its original is loose enough to merge two skills that happen to share
+boilerplate.
+
+This script re-derives the equivalent count against a real, already-built
+dense store: at `rag.NEAR_DUPLICATE_THRESHOLD` (or `--threshold`), it clusters
+every entry's chunk-0 vector by cosine similarity and reports how many
+clusters span more than one distinct `name` -- the same proxy for "different
+meaning" the byte-identical proof used.
+
+**Two numbers matter, not one.** Entries that already share a chunk-0 vector
+byte for byte cluster at *any* threshold, so a nonzero result is not
+automatically the threshold's fault. `--floor` reports that share-a-vector
+count on its own; the threshold is responsible only for the difference.
+
+A cosine threshold is a property of ONE embedding space. A bound measured in
+`BAAI/bge-small-en-v1.5` (384-d) says nothing about a `voyage-4` (1024-d)
+store -- rerun this against each space you intend to ship the collapse in.
+
+Usage:
+    export BOOST_HOME=~/.boost   # wherever the dense store already lives
+    python3 scripts/measure_near_duplicate_bound.py [--threshold 0.97] [--limit N]
+"""
+from __future__ import annotations
+
+import argparse
+import array
+import math
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from boost_cli.core import dense, rag
+
+
+def _load_numpy():
+    """numpy if importable, else None. It ships with the [rag] extra (via
+    onnxruntime), so it is present wherever a dense store can exist -- but this
+    script must still run without it rather than fail to start."""
+    try:
+        import numpy
+    except ImportError:
+        return None
+    return numpy
+
+
+def _norm(v: array.array) -> float:
+    return math.sqrt(sum(x * x for x in v))
+
+
+def _pairs_over_stdlib(vecs, norms, thresh):
+    """Yield (i, j) whose cosine is at/above `thresh`, in pure Python.
+
+    Norms are precomputed rather than recomputed per comparison: this is
+    O(n^2) either way, but the inner loop is a dot product alone.
+    """
+    n = len(vecs)
+    for i in range(n):
+        vi, ni = vecs[i], norms[i]
+        if ni == 0.0:
+            continue
+        for j in range(i + 1, n):
+            nj = norms[j]
+            if nj == 0.0:
+                continue
+            dot = sum(x * y for x, y in zip(vi, vecs[j], strict=True))
+            if dot / (ni * nj) >= thresh:
+                yield i, j
+
+
+def _pairs_over_numpy(np, vecs, thresh):
+    """Same pairs, as a blocked matmul. numpy ships with the [rag] extra."""
+    m = np.array(vecs, dtype=np.float32)
+    norms = np.linalg.norm(m, axis=1, keepdims=True)
+    norms[norms == 0] = 1.0
+    mn = m / norms
+    n = len(vecs)
+    for start in range(0, n, 512):
+        block = mn[start:start + 512] @ mn.T
+        for row in range(block.shape[0]):
+            i = start + row
+            for j in (block[row, i + 1:] >= thresh).nonzero()[0]:
+                yield i, i + 1 + int(j)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--threshold", type=float, default=rag.NEAR_DUPLICATE_THRESHOLD)
+    parser.add_argument("--limit", type=int, default=None,
+                        help="cap the number of distinct vectors compared (O(n^2))")
+    parser.add_argument("--floor", action="store_true",
+                        help="report only the share-a-vector count, no comparisons")
+    args = parser.parse_args(argv)
+
+    if not dense.ready():
+        print("no ready dense store -- run `boost reindex --dense` first", file=sys.stderr)
+        return 1
+    con = dense._connect()
+    if con is None:
+        print("dense store unusable here (sqlite-vec not loadable)", file=sys.stderr)
+        return 1
+    try:
+        rows = con.execute(
+            "SELECT chunks.name, vec_raw.id, vec_raw.embedding FROM chunks "
+            "JOIN vec_raw ON vec_raw.id = chunks.vid WHERE chunks.cix = 0"
+        ).fetchall()
+    finally:
+        con.close()
+    if not rows:
+        print("store has no chunk-0 vectors -- is it quantized? "
+              "(`boost reindex --dense` builds vec_raw)", file=sys.stderr)
+        return 1
+
+    # One entry per distinct VECTOR: entries whose chunk 0 is byte-identical
+    # already share a row, and comparing a vector with itself would report a
+    # free cluster that says nothing about the threshold.
+    by_vid: dict[int, tuple[set, array.array]] = {}
+    for name, vid, blob in rows:
+        names, _v = by_vid.setdefault(vid, (set(), array.array("f", blob)))
+        names.add(name)
+
+    vids = sorted(by_vid)
+    if args.limit:
+        vids = vids[:args.limit]
+    floor = sum(1 for v in vids if len(by_vid[v][0]) > 1)
+    print("%d entries over %d distinct chunk-0 vectors; %d of those vectors are "
+          "shared by more than one name already" % (len(rows), len(vids), floor))
+    if args.floor:
+        return 0
+
+    parent = list(range(len(vids)))
+
+    def find(x: int) -> int:
+        while parent[x] != x:
+            parent[x] = parent[parent[x]]
+            x = parent[x]
+        return x
+
+    vecs = [by_vid[v][1] for v in vids]
+    np = _load_numpy()
+    print("comparing %d vectors at threshold %.3f (%d pairs, %s)"
+          % (len(vids), args.threshold, len(vids) * (len(vids) - 1) // 2,
+             "numpy" if np is not None else "stdlib -- slow"))
+    gen = (_pairs_over_numpy(np, vecs, args.threshold) if np is not None
+           else _pairs_over_stdlib(vecs, [_norm(v) for v in vecs], args.threshold))
+
+    pairs_over = 0
+    for i, j in gen:
+        pairs_over += 1
+        ra, rb = find(i), find(j)
+        if ra != rb:
+            parent[ra] = rb
+
+    clusters: dict[int, set] = {}
+    for i in range(len(vids)):
+        clusters.setdefault(find(i), set()).update(by_vid[vids[i]][0])
+    spanning = {r: n for r, n in clusters.items() if len(n) > 1}
+
+    print("%d pairs at/above threshold, %d clusters, %d span more than one name "
+          "(%d of those from vectors already shared, %d added by the threshold)"
+          % (pairs_over, len(clusters), len(spanning), floor, len(spanning) - floor))
+    for _root, names in sorted(spanning.items(), key=lambda kv: -len(kv[1]))[:20]:
+        print("  spans %d: %s" % (len(names), ", ".join(sorted(names))[:160]))
+    return 1 if spanning else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())