dirsql-plugin-embeddings 0.1.0__tar.gz → 0.1.2__tar.gz

{dirsql_plugin_embeddings-0.1.0 → dirsql_plugin_embeddings-0.1.2}/.gitignore

@@ -56,3 +56,6 @@ docs/playwright-report/
 docs/blob-report/
 docs/.playwright/
 actionlint
+
+# cargo-mutants run output (never commit)
+mutants.out/

dirsql_plugin_embeddings-0.1.2/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: dirsql-plugin-embeddings
+Version: 0.1.2
+Summary: First-party dirsql plugin: semantic search via an OpenAI-compatible embeddings endpoint.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# dirsql-plugin-embeddings
+
+A first-party [`dirsql`](https://github.com/thekevinscott/dirsql) plugin that
+adds **semantic search** over a directory of Markdown files. It is the worked
+implementation behind the [Search documents by
+meaning](https://thekevinscott.github.io/dirsql/howto/search-by-meaning) how-to,
+swapping that guide's local `model2vec` model for any OpenAI-compatible
+`/v1/embeddings` endpoint.
+
+```sh
+uvx --with dirsql-plugin-embeddings dirsql
+```
+
+Deliberately minimal (v0.1): one embedding provider shape, one table, no
+chunking, no config surface beyond three environment variables.
+
+## How it works
+
+The plugin ships a `dirsql.toml` fragment that dirsql discovers when the package
+is installed alongside it. The fragment declares:
+
+- the [`sqlite-vec`](https://github.com/asg017/sqlite-vec) extension, for
+  `vec_distance_cosine()`;
+- a `documents` table whose `on-file` hook embeds each `**/*.md` file into a
+  TEXT `embedding` column;
+- a `pre-query` hook that embeds the incoming question and emits the
+  nearest-neighbor SQL.
+
+Both hooks are console scripts that call the same embedder.
+
+## Configuration
+
+The embedder reads three environment variables (point them at any hosted or
+self-managed OpenAI-compatible inference server):
+
+| Variable | Meaning |
+|---|---|
+| `DIRSQL_EMBEDDINGS_BASE_URL` | Base URL; `/v1/embeddings` is appended. |
+| `DIRSQL_EMBEDDINGS_MODEL` | Model name sent in the request. |
+| `DIRSQL_EMBEDDINGS_API_KEY` | Bearer token for `Authorization`. |
+
+## Console scripts
+
+| Script | Hook | Input | Output |
+|---|---|---|---|
+| `dirsql-embeddings-on-file` | `on-file` | a file's absolute path (`argv[1]`) | one-line JSON row array with `path`, `text`, `embedding` |
+| `dirsql-embeddings-pre-query` | `pre-query` | a raw request body (`argv[1]`) | nearest-neighbor SQL over `documents` |
+
+`pre-query` accepts both a verbatim server body (`{"q": ...}`) and the CLI
+`query` subcommand's `{"sql": <arg>}` wrapper, so `dirsql query '{"q": ...}'` and
+a real `POST /query` both work.
+
+## Tests
+
+Three tiers, per the dirsql testing conventions:
+
+- **unit** (colocated, mocked seams) — `src/dirsql_plugin_embeddings/*_test.py`
+- **integration** (`tests/integration/`) — each console script as a real
+  subprocess against a local stub `/v1/embeddings` server
+- **e2e** (`tests/e2e/`) — the full loop through the real launcher + `dirsql`
+  binary + `sqlite-vec`, nothing mocked but the embedding endpoint

{dirsql_plugin_embeddings-0.1.0 → dirsql_plugin_embeddings-0.1.2}/README.md

@@ -3,13 +3,16 @@
 A first-party [`dirsql`](https://github.com/thekevinscott/dirsql) plugin that
 adds **semantic search** over a directory of Markdown files. It is the worked
 implementation behind the [Search documents by
-meaning](../../docs/howto/search-by-meaning.md) how-to, swapping that guide's
-local `model2vec` model for any OpenAI-compatible `/v1/embeddings` endpoint.
+meaning](https://thekevinscott.github.io/dirsql/howto/search-by-meaning) how-to,
+swapping that guide's local `model2vec` model for any OpenAI-compatible
+`/v1/embeddings` endpoint.
 
-This is an **in-repo, repo-only** package (not published to an index). It exists
-to prove the dirsql plugin conventions (#531, part of #363) and power the
-semantic-search demo. Deliberately minimal (v0.1): one embedding provider shape,
-one table, no chunking, no config surface beyond three environment variables.
+```sh
+uvx --with dirsql-plugin-embeddings dirsql
+```
+
+Deliberately minimal (v0.1): one embedding provider shape, one table, no
+chunking, no config surface beyond three environment variables.
 
 ## How it works
 

dirsql_plugin_embeddings-0.1.0/e2e-attestations/claude-open-issues-review-le8hm5-531.json → dirsql_plugin_embeddings-0.1.2/e2e-attestations/claude-on-file-integration-e2e-lpeicb.json

@@ -1,7 +1,7 @@
 {
   "command": "uv run --with sqlite-vec --with-editable . --with-editable ../../packages/python python -m pytest tests/e2e -x -q",
-  "ran_at": 1784022840,
+  "ran_at": 1785323892,
   "exit_code": 0,
-  "commit": "5f6caffd4996dfdf09cf798c1deb55f6e216fde5",
-  "branch": "claude/open-issues-review-le8hm5-531"
+  "commit": "35c1c6929c4a8b517032cc51e0cc6720f43b58f4",
+  "branch": "claude/on-file-integration-e2e-lpeicb"
 }

{dirsql_plugin_embeddings-0.1.0 → dirsql_plugin_embeddings-0.1.2}/pyproject.toml

@@ -10,6 +10,7 @@ build-backend = "hatchling.build"
 name = "dirsql-plugin-embeddings"
 dynamic = ["version"]
 description = "First-party dirsql plugin: semantic search via an OpenAI-compatible embeddings endpoint."
+readme = "README.md"
 requires-python = ">=3.11"
 
 [tool.hatch.version]
@@ -38,7 +39,7 @@ git_describe_command = ["git", "describe", "--dirty", "--tags", "--long", "--mat
 [project.scripts]
 # The two command hooks the fragment invokes; installing the package puts them
 # on PATH so `dirsql` resolves them when it spawns the hooks.
-dirsql-embeddings-on-file = "dirsql_plugin_embeddings.on_file:main"
+dirsql-embeddings-on-file = "dirsql_plugin_embeddings.on_file:on_file"
 dirsql-embeddings-pre-query = "dirsql_plugin_embeddings.pre_query:main"
 
 [project.entry-points.dirsql]

dirsql_plugin_embeddings-0.1.2/src/dirsql_plugin_embeddings/on_file/__init__.py

@@ -0,0 +1,11 @@
+"""``on-file`` console script: embed one matched file into a dirsql row.
+
+The package barrel: ``pyproject.toml`` points the ``dirsql-embeddings-on-file``
+script at ``dirsql_plugin_embeddings.on_file:on_file``, which resolves here, so
+this re-export is the shipped command's public surface -- moving the callable
+between modules is free, dropping it from ``__all__`` breaks the install.
+"""
+
+from .on_file import on_file
+
+__all__ = ["on_file"]

dirsql_plugin_embeddings-0.1.2/src/dirsql_plugin_embeddings/on_file/build_rows.py

@@ -0,0 +1,13 @@
+"""Shape one embedded file into the command hook's row array.
+
+Annotations are evaluated at runtime (no ``from __future__ import
+annotations``) so a mutated ``X | None`` union in a signature fails at import
+rather than surviving as an inert string.
+"""
+
+import json
+
+
+def build_rows(path: str, text: str, vector: list[float]) -> list[dict]:
+    # The embedding is stored as JSON text, which `sqlite-vec` accepts directly.
+    return [{"path": path, "text": text, "embedding": json.dumps(vector)}]

dirsql_plugin_embeddings-0.1.2/src/dirsql_plugin_embeddings/on_file/on_file.py

@@ -0,0 +1,25 @@
+"""The ``on-file`` hook entry point.
+
+Reads the file at ``argv[1]``, embeds its text, and prints a one-line JSON row
+array (``path``, ``text``, ``embedding``).
+
+Annotations are evaluated at runtime (no ``from __future__ import
+annotations``) so a mutated ``X | None`` union in a signature fails at import
+rather than surviving as an inert string.
+"""
+
+import json
+import sys
+
+from ..embedder import embed
+from .build_rows import build_rows
+from .read_text import read_text
+
+
+def on_file(argv: list[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv
+    path = argv[1]
+    text = read_text(path)
+    print(json.dumps(build_rows(path, text, embed(text))))
+    return 0

dirsql_plugin_embeddings-0.1.2/src/dirsql_plugin_embeddings/on_file/read_text.py

@@ -0,0 +1,11 @@
+"""Read the matched file's text off disk.
+
+Annotations are evaluated at runtime (no ``from __future__ import
+annotations``) so a mutated ``X | None`` union in a signature fails at import
+rather than surviving as an inert string.
+"""
+
+
+def read_text(path: str) -> str:
+    with open(path, encoding="utf-8") as handle:
+        return handle.read()

dirsql_plugin_embeddings-0.1.0/PKG-INFO

@@ -1,5 +0,0 @@
-Metadata-Version: 2.4
-Name: dirsql-plugin-embeddings
-Version: 0.1.0
-Summary: First-party dirsql plugin: semantic search via an OpenAI-compatible embeddings endpoint.
-Requires-Python: >=3.11

dirsql_plugin_embeddings-0.1.0/src/dirsql_plugin_embeddings/on_file.py

@@ -1,33 +0,0 @@
-"""``on-file`` console script: embed one matched file into a dirsql row.
-
-Reads the file at ``argv[1]``, embeds its text, and prints a one-line JSON row
-array (``path``, ``text``, ``embedding``) -- the embedding stored as JSON text,
-which ``sqlite-vec`` accepts directly.
-
-Annotations are evaluated at runtime (no ``from __future__ import annotations``)
-so a mutated ``X | None`` union in a signature fails at import rather than
-surviving as an inert string.
-"""
-
-import json
-import sys
-
-from .embedder import embed
-
-
-def _read_text(path: str) -> str:
-    with open(path, encoding="utf-8") as handle:
-        return handle.read()
-
-
-def build_rows(path: str, text: str, vector: list[float]) -> list[dict]:
-    return [{"path": path, "text": text, "embedding": json.dumps(vector)}]
-
-
-def main(argv: list[str] | None = None) -> int:
-    if argv is None:
-        argv = sys.argv
-    path = argv[1]
-    text = _read_text(path)
-    print(json.dumps(build_rows(path, text, embed(text))))
-    return 0