@mrplex/embedder 0.1.0 → 0.1.3

package/README.md

@@ -1,7 +1,7 @@
 # @mrplex/embedder
 
 A ready-to-use local embedding provider for [mrplex](https://github.com/usergenic/mrplex)'s
-`--embed-cmd` hook. It runs `bge-small-en-v1.5` (384-dim) on CPU via ONNX — no GPU, no
+`--embedder` hook. It runs `bge-small-en-v1.5` (384-dim) on CPU via ONNX — no GPU, no
 separate service. mrplex spawns it once and keeps it resident, so the model loads a single
 time and each batch is one JSON line in / one JSON line out.
 
@@ -19,8 +19,9 @@ embeddings.
 npm install -g @mrplex/embedder
 ```
 
-The model (~130 MB) auto-downloads and caches on first run (typically under
-`~/.cache/huggingface` or fastembed's cache directory).
+The model (~130 MB) auto-downloads on first run and caches under
+`~/.cache/mrplex/embedder` (or `$XDG_CACHE_HOME/mrplex/embedder`). Override with
+`MRPLEX_EMBEDDER_CACHE` or `--cache-dir PATH`.
 
 **From the mrplex monorepo** (development):
 
@@ -30,34 +31,34 @@ cd packages/embedder && npm install
 
 ## Use with mrplex
 
-After a global install, point mrplex at the `mrplex-embedder` binary:
+After a global install:
 
 ```bash
 # Serve with the hook — every write auto-embeds.
-mrplex serve --unsafe --embed-cmd "mrplex-embedder --stdio"
+mrplex serve --unsafe --embedder mrplex-embedder
 
 # One-off backfill of an existing repo.
-mrplex embed backfill -r notes --embed-cmd "mrplex-embedder --stdio"
+mrplex embed backfill -r notes --embedder mrplex-embedder
 
-# Or make it ambient.
-export MRPLEX_EMBED_CMD="mrplex-embedder --stdio"
+# Or make it ambient for every mrplex command:
+export MRPLEX_EMBEDDER=mrplex-embedder
+# mrplex config set-embedder mrplex-embedder   # same thing, persisted
 ```
 
 **Monorepo / local checkout** (no global install):
 
 ```bash
-mrplex serve --unsafe \
-  --embed-cmd "node packages/embedder/embedder.mjs --stdio"
+mrplex serve --unsafe --embedder "node packages/embedder/embedder.mjs"
 ```
 
 ### Different models
 
 ```bash
 # Stronger, slower (768-dim).
-export MRPLEX_EMBED_CMD="mrplex-embedder --stdio --model fast-bge-base-en-v1.5"
+export MRPLEX_EMBEDDER="mrplex-embedder --model fast-bge-base-en-v1.5"
 
 # Matryoshka truncation (re-embed after changing --dim).
-export MRPLEX_EMBED_CMD="mrplex-embedder --stdio --dim 256"
+export MRPLEX_EMBEDDER="mrplex-embedder --dim 256"
 ```
 
 List supported model keys:
@@ -68,13 +69,17 @@ mrplex-embedder --list-models
 
 ## Flags
 
-- `--stdio` — required transport (one JSON line per batch over stdin/stdout).
 - `--model KEY` — any `fastembed` model key. Default `fast-bge-small-en-v1.5`.
   Others include `fast-all-MiniLM-L6-v2`, `fast-bge-base-en-v1.5`,
   `fast-multilingual-e5-large`. Run `--list-models` for the full set.
 - `--dim N` — truncate + re-normalize each vector to `N` dims (for Matryoshka
   models). The truncation is encoded into the reported model string
   (`<key>@<N>`) so mrplex treats a dim change as a model change and re-embeds.
+- `--cache-dir PATH` — where ONNX model archives are stored. Default
+  `$MRPLEX_EMBEDDER_CACHE`, else `$XDG_CACHE_HOME/mrplex/embedder` or
+  `~/.cache/mrplex/embedder`.
+- `--stdio` — optional no-op; stdio is the default transport (one JSON line
+  per batch over stdin/stdout).
 - `--list-models` — print supported `--model` keys and exit.
 - `--help`, `--version` — usage and version.
 

package/embedder.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Local embedding provider for mrplex's `--embed-cmd` hook.
+ * Local embedding provider for mrplex's `--embedder` hook.
  *
  * Speaks the subprocess contract (design §5.3): one JSON line in on stdin
  * `{ chunks: string[] }`, one JSON line out on stdout
@@ -8,8 +8,8 @@
  * ONCE and reuses it for every batch (src/embed/cmd-hook.ts), so the model
  * loads a single time and stays resident — no per-call cold start.
  *
- *   mrplex serve --unsafe --embed-cmd "mrplex-embedder --stdio"
- *   mrplex embed backfill -r notes --embed-cmd "mrplex-embedder --stdio"
+ *   mrplex serve --unsafe --embedder mrplex-embedder
+ *   mrplex embed backfill -r notes --embedder mrplex-embedder
  *
  * Model: bge-small-en-v1.5 (384-dim) by default — strong retrieval quality for
  * its size, and small vectors keep mrplex's brute-force cosine scan fast. Runs
@@ -17,10 +17,18 @@
  */
 
 import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { createInterface } from "node:readline";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
+/** Where fastembed stores downloaded ONNX model archives (not HuggingFace hub). */
+function defaultCacheDir() {
+  if (process.env.MRPLEX_EMBEDDER_CACHE) return process.env.MRPLEX_EMBEDDER_CACHE;
+  const xdgCache = process.env.XDG_CACHE_HOME || join(homedir(), ".cache");
+  return join(xdgCache, "mrplex", "embedder");
+}
+
 const pkg = JSON.parse(
   readFileSync(join(dirname(fileURLToPath(import.meta.url)), "package.json"), "utf8"),
 );
@@ -35,15 +43,16 @@ const has = (name) => argv.includes(name);
 
 function printHelp() {
   console.error(`mrplex-embedder ${VERSION}
-Local CPU embedding provider for mrplex's --embed-cmd hook.
+Local CPU embedding provider for mrplex's --embedder hook.
 
 Usage:
-  mrplex-embedder --stdio [--model KEY] [--dim N]
+  mrplex-embedder [--model KEY] [--dim N] [--cache-dir PATH]
 
 Options:
-  --stdio          required transport (one JSON line per batch over stdin/stdout)
+  --stdio          optional; stdio is the default (one JSON line per batch over stdin/stdout)
   --model KEY      fastembed model key (default: fast-bge-small-en-v1.5)
   --dim N          truncate + re-normalize to N dims (Matryoshka models only)
+  --cache-dir PATH model download cache (default: $MRPLEX_EMBEDDER_CACHE or ~/.cache/mrplex/embedder)
   --list-models    print supported --model keys and exit
   --help, -h       show this help
   --version, -V    print version
@@ -63,6 +72,7 @@ if (has("--version") || has("-V")) {
 
 const modelKey = flag("--model", "fast-bge-small-en-v1.5");
 const truncateDim = argv.includes("--dim") ? Number.parseInt(flag("--dim", ""), 10) : null;
+const cacheDir = argv.includes("--cache-dir") ? flag("--cache-dir", "") : defaultCacheDir();
 
 if (truncateDim !== null && (!Number.isInteger(truncateDim) || truncateDim <= 0)) {
   console.error(`embedder: --dim must be a positive integer (got ${flag("--dim", "")})`);
@@ -89,11 +99,6 @@ if (has("--list-models")) {
   process.exit(0);
 }
 
-if (!has("--stdio")) {
-  printHelp();
-  process.exit(2);
-}
-
 // fastembed keys its models by an enum whose values are the string keys above.
 const model = Object.values(EmbeddingModel).find((v) => v === modelKey);
 if (!model) {
@@ -104,7 +109,7 @@ if (!model) {
 }
 
 // maxLength covers the chunker's 2000-char cap (~512 tokens); bge tops out at 512.
-const embedder = await FlagEmbedding.init({ model, maxLength: 512 });
+const embedder = await FlagEmbedding.init({ model, maxLength: 512, cacheDir });
 
 /** Truncate a unit vector to `n` dims and re-normalize (Matryoshka). */
 function truncate(vec, n) {
@@ -186,5 +191,5 @@ rl.on("line", (line) => {
 });
 
 console.error(
-  `embedder stdio model=${modelKey}${truncateDim !== null ? ` dim=${truncateDim}` : ""}`,
+  `embedder stdio model=${modelKey}${truncateDim !== null ? ` dim=${truncateDim}` : ""} cache=${cacheDir}`,
 );

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mrplex/embedder",
-  "version": "0.1.0",
-  "description": "Local CPU embedding provider for mrplex's --embed-cmd hook (bge-small-en-v1.5 via fastembed). Isolated from mrplex core so fastembed/tar stay out of the core dependency graph.",
+  "version": "0.1.3",
+  "description": "Local CPU embedding provider for mrplex's --embedder hook (bge-small-en-v1.5 via fastembed). Isolated from mrplex core so fastembed/tar stay out of the core dependency graph.",
   "type": "module",
   "license": "MIT",
   "author": "Brendan Baldwin <brendan@usergenic.com>",
@@ -33,7 +33,8 @@
     "README.md"
   ],
   "scripts": {
-    "start": "node embedder.mjs --stdio",
+    "pretest": "node -e \"try{require.resolve('fastembed')}catch{console.error('pretest: run npm install first');process.exit(1)}\"",
+    "start": "node embedder.mjs",
     "test": "node --test test/*.test.mjs"
   },
   "engines": {