dirsql-plugin-embeddings 0.1.17__tar.gz → 0.1.19__tar.gz

{dirsql_plugin_embeddings-0.1.17 → dirsql_plugin_embeddings-0.1.19}/.gitignore

@@ -57,5 +57,7 @@ docs/blob-report/
 docs/.playwright/
 actionlint
 
-# cargo-mutants run output (never commit)
+# cargo-mutants run output (never commit). The tool rotates the previous
+# run's directory to `.old` on every re-run, so both forms need ignoring.
 mutants.out/
+mutants.out.old/

{dirsql_plugin_embeddings-0.1.17 → dirsql_plugin_embeddings-0.1.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dirsql-plugin-embeddings
-Version: 0.1.17
+Version: 0.1.19
 Summary: First-party dirsql plugin: semantic search over files.
 Requires-Python: >=3.10
 Requires-Dist: cachetta>=0.7

dirsql_plugin_embeddings-0.1.19/changelog.d/2026-09-04-report-cache-hits.md

@@ -0,0 +1,3 @@
+**Added**
+
+- **The worker now tells dirsql which embeddings cost nothing.** Every `ok` response carries `"meta": {"cached": <bool>}`, so the progress line can split its worker-call count — `dirsql: ran 41231 worker calls in 2m41s (38104 cached)` — instead of reporting one undifferentiated total for a run that was mostly disk reads. `cachetta`'s wrapper returns a hit and a miss identically, so the flag is recovered from whether the wrapped compute actually ran. (#1034)

dirsql_plugin_embeddings-0.1.19/changelog.d/2026-09-05-one-function-per-file.md

@@ -0,0 +1,7 @@
+**Changed**
+
+Split `search/sql.py`, `search/run.py`, and `embedding/model.py` into one
+module per non-trivial function, so the tree is clean at
+`one-function-per-file`'s strictest threshold. Every symbol keeps its behavior;
+`search.run._search` is now `search.search_rows.search_rows`, and the SQL
+builders moved to modules named for them.

dirsql_plugin_embeddings-0.1.19/e2e-attestations/claude-1095-ofpf-embeddings.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run --with-editable ../../packages/python python -m pytest tests/e2e/ -x -q",
+  "ran_at": 1788575701,
+  "exit_code": 0,
+  "commit": "8f07e97547e3c145e6e6635e89839b6318d25b7c",
+  "branch": "claude/1095-ofpf-embeddings"
+}

dirsql_plugin_embeddings-0.1.19/e2e-attestations/claude-tackle-1034-plugin-flag.json

@@ -0,0 +1,7 @@
+{
+  "command": "uv run --with-editable ../../packages/python python -m pytest tests/e2e/ -x -q",
+  "ran_at": 1788558384,
+  "exit_code": 0,
+  "commit": "fc3ee82adb022a9b6da85687695ca752dd178f03",
+  "branch": "claude/tackle-1034-plugin-flag"
+}

dirsql_plugin_embeddings-0.1.19/migrations.d/2026-09-04-report-cache-hits.md

@@ -0,0 +1,39 @@
+### dirsql-plugin-embeddings: `ok` responses now carry cache metadata
+
+#### Summary
+
+The worker's success responses gain an optional `"meta"` object:
+`{"ok": [floats...], "meta": {"cached": true|false}}`. Nothing is removed and
+no signature a user calls changes — the plugin exports no Python API, and its
+CLI arguments, exit codes and vectors are all untouched. The one observable
+difference is the extra key on the wire, and the progress line dirsql draws
+from it.
+
+#### Required changes
+
+_None._
+
+#### Deprecations removed
+
+_None._
+
+#### Behavior changes without code changes
+
+- A worker `ok` line previously read `{"ok": [1.0, 0.0]}` and now reads
+  `{"ok": [1.0, 0.0], "meta": {"cached": false}}`. dirsql ignores unknown keys,
+  so this is additive for it; a third party parsing worker output with an
+  exact-equality check on the whole object will see a mismatch and should
+  compare `response["ok"]` instead.
+- `{"ok": null}` for a NULL value is unchanged — no compute is attempted, so
+  there is no cache state to report.
+- With the plugin installed, `dirsql` runs that hit the on-disk cache now show
+  the split in the progress line (`ran 41231 worker calls in 2m41s
+  (38104 cached)`). A run with no hits looks exactly as it did before.
+
+#### Verification
+
+```bash
+printf '{"call": ["hello"]}\n{"call": ["hello"]}\n' \
+  | uvx --from dirsql-plugin-embeddings dirsql-plugin-embeddings worker
+# expected: first line "cached":false, second line "cached":true
+```

dirsql_plugin_embeddings-0.1.19/src/dirsql_plugin_embeddings/embedding/model.py

@@ -0,0 +1,7 @@
+DEFAULT_MODEL_ID = "minishlab/potion-retrieval-32M"
+
+
+def load_model(model_id):
+    from model2vec import StaticModel
+
+    return StaticModel.from_pretrained(model_id)

dirsql_plugin_embeddings-0.1.17/src/dirsql_plugin_embeddings/embedding/model.py → dirsql_plugin_embeddings-0.1.19/src/dirsql_plugin_embeddings/embedding/model_identifier.py

@@ -1,12 +1,3 @@
-DEFAULT_MODEL_ID = "minishlab/potion-retrieval-32M"
-
-
-def load_model(model_id):
-    from model2vec import StaticModel
-
-    return StaticModel.from_pretrained(model_id)
-
-
 def model_identifier(model_id, model):
     config = getattr(model, "config", None) or {}
     version = config.get("model2vec_version")

{dirsql_plugin_embeddings-0.1.17 → dirsql_plugin_embeddings-0.1.19}/src/dirsql_plugin_embeddings/embedding/worker.py

@@ -3,6 +3,7 @@ from hashlib import sha256
 
 from . import model
 from .cache import make_cache
+from .model_identifier import model_identifier
 from .values import ProtocolError, decode_value
 
 MALFORMED_SHAPE = (
@@ -18,6 +19,7 @@ class Worker:
         self._cache = make_cache()
         self._compute_cached = self._cache.wrap(self._compute)
         self._pending = None
+        self._computed = False
 
     def _model(self, model_id):
         if model_id not in self._models:
@@ -25,6 +27,10 @@ class Worker:
         return self._models[model_id]
 
     def _compute(self, digest, identifier):
+        # cachetta's wrapper returns a hit and a miss identically, so the only
+        # place a miss is observable is here: _compute runs on a miss and never
+        # on a hit. embed() clears the flag and reads it back afterwards.
+        self._computed = True
         text, loaded = self._pending
         # No progress bar: the protocol embeds one value per round trip, so a
         # per-call bar can only ever say 1/1. The model *download* bar, which
@@ -33,11 +39,21 @@ class Worker:
         return [float(component) for component in vector]
 
     def embed(self, text, model_id):
+        """Return the vector for ``text``, and whether the cache served it."""
         loaded = self._model(model_id)
-        identifier = model.model_identifier(model_id, loaded)
+        identifier = model_identifier(model_id, loaded)
         digest = sha256(text.encode("utf-8")).hexdigest()
         self._pending = (text, loaded)
-        return self._compute_cached(digest, identifier)
+        self._computed = False
+        vector = self._compute_cached(digest, identifier)
+        return vector, not self._computed
+
+    def _embed_response(self, text, model_id):
+        try:
+            vector, cached = self.embed(text, model_id)
+        except Exception as error:
+            return {"err": f"embed({model_id!r}) failed: {error}"}
+        return {"ok": vector, "meta": {"cached": cached}}
 
     def handle(self, line):
         try:
@@ -59,10 +75,7 @@ class Worker:
         (model_id,) = rest or [model.DEFAULT_MODEL_ID]
         if not isinstance(model_id, str):
             return {"err": MALFORMED_MODEL_ID}
-        try:
-            return {"ok": self.embed(text, model_id)}
-        except Exception as error:
-            return {"err": f"embed({model_id!r}) failed: {error}"}
+        return self._embed_response(text, model_id)
 
     def serve(self, stdin, stdout):
         for line in stdin:

dirsql_plugin_embeddings-0.1.19/src/dirsql_plugin_embeddings/search/build_search_sql.py

@@ -0,0 +1,18 @@
+from .embed_call import embed_call
+from .normalize_glob import normalize_glob
+from .quote import quote
+
+
+def build_search_sql(glob, query, limit, model=None):
+    outer = embed_call(quote(query), model)
+    inner = embed_call("content", model)
+    # A matched file that is unreadable, not valid UTF-8, or deleted mid-scan
+    # has NULL content, so its embedding is NULL too. Dropping those rows is
+    # what keeps the ranking honest: a NULL distance sorts FIRST ascending in
+    # SQLite, so unrankable files would otherwise take the top-k slots.
+    return (
+        f"SELECT path, vec_distance_cosine(emb, {outer}) AS distance"
+        f" FROM (SELECT path, {inner} AS emb FROM {quote(normalize_glob(glob))})"
+        f" WHERE emb IS NOT NULL"
+        f" ORDER BY distance LIMIT {int(limit):d}"
+    )

dirsql_plugin_embeddings-0.1.19/src/dirsql_plugin_embeddings/search/count_corpus_sql.py

@@ -0,0 +1,6 @@
+from .normalize_glob import normalize_glob
+from .quote import quote
+
+
+def count_corpus_sql(glob):
+    return f"SELECT COUNT(*) AS n FROM {quote(normalize_glob(glob))}"

dirsql_plugin_embeddings-0.1.19/src/dirsql_plugin_embeddings/search/embed_call.py

@@ -0,0 +1,7 @@
+from .quote import quote
+
+
+def embed_call(argument, model):
+    if model is None:
+        return f"embed({argument})"
+    return f"embed({argument}, {quote(model)})"

dirsql_plugin_embeddings-0.1.19/src/dirsql_plugin_embeddings/search/no_rows_message.py

@@ -0,0 +1,7 @@
+def no_rows_message(glob, matched, root):
+    if not matched:
+        return f"no files matched {glob!r} (searched from {root})"
+    return (
+        f"{glob!r} matched {matched} file(s), but none had text content to"
+        f" embed -- unreadable or not valid UTF-8 (searched from {root})"
+    )

dirsql_plugin_embeddings-0.1.19/src/dirsql_plugin_embeddings/search/normalize_glob.py

@@ -0,0 +1,11 @@
+PATH_PREFIXES = ("./", "../", "/", "~/")
+
+
+def normalize_glob(glob):
+    # The core only rescues path-shaped missing tables (./, ../, /, ~/); a
+    # bare relative glob like '**/*.md' would error with a "did you mean
+    # './...'" hint. Here GLOB is unambiguously a corpus glob, so spare the
+    # user the round trip.
+    if glob.startswith(PATH_PREFIXES):
+        return glob
+    return f"./{glob}"

dirsql_plugin_embeddings-0.1.19/src/dirsql_plugin_embeddings/search/quote.py

@@ -0,0 +1,3 @@
+def quote(text):
+    escaped = text.replace("'", "''")
+    return f"'{escaped}'"

dirsql_plugin_embeddings-0.1.19/src/dirsql_plugin_embeddings/search/run.py

@@ -0,0 +1,17 @@
+import asyncio
+import os
+
+from .no_rows_message import no_rows_message
+from .output import format_rows
+from .search_rows import search_rows
+
+
+class NothingToRank(Exception):
+    """The search produced no rows, and why -- so the CLI can say which."""
+
+
+def run_search(glob, query, limit, model=None):
+    rows, matched = asyncio.run(search_rows(glob, query, limit, model))
+    if not rows:
+        raise NothingToRank(no_rows_message(glob, matched, os.getcwd()))
+    return format_rows(rows)

dirsql_plugin_embeddings-0.1.19/src/dirsql_plugin_embeddings/search/search_rows.py

@@ -0,0 +1,23 @@
+from importlib import resources
+
+import dirsql
+
+from .build_search_sql import build_search_sql
+from .count_corpus_sql import count_corpus_sql
+
+
+def config_fragment():
+    return str(resources.files("dirsql_plugin_embeddings").joinpath("dirsql.toml"))
+
+
+async def search_rows(glob, query, limit, model):
+    db = dirsql.DirSQL(config=config_fragment())
+    rows = await db.query(build_search_sql(glob, query, limit, model))
+    if rows:
+        return rows, None
+    # Only now, on the error path, is the second scan worth its cost: it is
+    # what tells "no files matched" apart from "matched, none embeddable".
+    # One row, always: `SELECT COUNT(*)` cannot return anything else, and
+    # unpacking says so rather than trusting an index.
+    (counted,) = await db.query(count_corpus_sql(glob))
+    return rows, counted["n"]

{dirsql_plugin_embeddings-0.1.17 → dirsql_plugin_embeddings-0.1.19}/testing-conventions.toml

@@ -2,6 +2,9 @@
 # package. Mirrors internals/checks: python coverage floor 100 + branch, zero
 # exemptions, and deliberately no `[e2e] extra_scope` -- this package compiles
 # none of packages/rust/src, so a core change never stales its attestation.
+[python]
+one_function_per_file = { max_lines = 10 }
+
 [python.coverage]
 fail_under = 100
 branch = true

dirsql_plugin_embeddings-0.1.17/src/dirsql_plugin_embeddings/search/run.py

@@ -1,45 +0,0 @@
-import asyncio
-import os
-from importlib import resources
-
-import dirsql
-
-from .output import format_rows
-from .sql import build_search_sql, count_corpus_sql
-
-
-class NothingToRank(Exception):
-    """The search produced no rows, and why -- so the CLI can say which."""
-
-
-def config_fragment():
-    return str(resources.files("dirsql_plugin_embeddings").joinpath("dirsql.toml"))
-
-
-def no_rows_message(glob, matched, root):
-    if not matched:
-        return f"no files matched {glob!r} (searched from {root})"
-    return (
-        f"{glob!r} matched {matched} file(s), but none had text content to"
-        f" embed -- unreadable or not valid UTF-8 (searched from {root})"
-    )
-
-
-async def _search(glob, query, limit, model):
-    db = dirsql.DirSQL(config=config_fragment())
-    rows = await db.query(build_search_sql(glob, query, limit, model))
-    if rows:
-        return rows, None
-    # Only now, on the error path, is the second scan worth its cost: it is
-    # what tells "no files matched" apart from "matched, none embeddable".
-    # One row, always: `SELECT COUNT(*)` cannot return anything else, and
-    # unpacking says so rather than trusting an index.
-    (counted,) = await db.query(count_corpus_sql(glob))
-    return rows, counted["n"]
-
-
-def run_search(glob, query, limit, model=None):
-    rows, matched = asyncio.run(_search(glob, query, limit, model))
-    if not rows:
-        raise NothingToRank(no_rows_message(glob, matched, os.getcwd()))
-    return format_rows(rows)

dirsql_plugin_embeddings-0.1.17/src/dirsql_plugin_embeddings/search/sql.py

@@ -1,41 +0,0 @@
-PATH_PREFIXES = ("./", "../", "/", "~/")
-
-
-def quote(text):
-    escaped = text.replace("'", "''")
-    return f"'{escaped}'"
-
-
-def normalize_glob(glob):
-    # The core only rescues path-shaped missing tables (./, ../, /, ~/); a
-    # bare relative glob like '**/*.md' would error with a "did you mean
-    # './...'" hint. Here GLOB is unambiguously a corpus glob, so spare the
-    # user the round trip.
-    if glob.startswith(PATH_PREFIXES):
-        return glob
-    return f"./{glob}"
-
-
-def embed_call(argument, model):
-    if model is None:
-        return f"embed({argument})"
-    return f"embed({argument}, {quote(model)})"
-
-
-def build_search_sql(glob, query, limit, model=None):
-    outer = embed_call(quote(query), model)
-    inner = embed_call("content", model)
-    # A matched file that is unreadable, not valid UTF-8, or deleted mid-scan
-    # has NULL content, so its embedding is NULL too. Dropping those rows is
-    # what keeps the ranking honest: a NULL distance sorts FIRST ascending in
-    # SQLite, so unrankable files would otherwise take the top-k slots.
-    return (
-        f"SELECT path, vec_distance_cosine(emb, {outer}) AS distance"
-        f" FROM (SELECT path, {inner} AS emb FROM {quote(normalize_glob(glob))})"
-        f" WHERE emb IS NOT NULL"
-        f" ORDER BY distance LIMIT {int(limit):d}"
-    )
-
-
-def count_corpus_sql(glob):
-    return f"SELECT COUNT(*) AS n FROM {quote(normalize_glob(glob))}"