@tryformation/querylight-cli 0.2.3 → 0.2.4

package/README.md

@@ -16,6 +16,7 @@ It is designed for local, inspectable workflows:
 - chunk documents for retrieval
 - build a portable local Querylight index
 - search and generate retrieval context for external agents and tools
+- serve an OpenSearch-like `_search` API over one or more local knowledge bases
 - inspect workspace state, diffs, and change reports
 
 ## Install
@@ -108,6 +109,9 @@ Search it:
 qli search "API authentication"
 qli search --source-type rss --since 2026-05-01 --has-publication-date
 qli search-json '{"query":{"match":{"text":"API authentication"}},"size":5}'
+curl -X POST http://127.0.0.1:3000/_search \
+  -H 'content-type: application/json' \
+  -d '{"query":{"match":{"text":"API authentication"}},"size":5}'
 ```
 
 Find related documents for an existing one:
@@ -122,6 +126,16 @@ Generate retrieval context:
 qli context "How do I authenticate API requests?" --top-k 8
 ```
 
+Serve the lexical index over HTTP:
+
+```bash
+qli serve
+```
+
+`qli serve` loads the current workspace index once at startup and reuses it for each request.
+Use `POST /_search` or `POST /<configured-index-name>/_search` for a single workspace.
+Use `POST /<directory-name>/_search` when `--workspace` points to a directory whose children each contain their own `.kb` workspace.
+
 ## Example Skill: `qli` with `bunx` and `uv`
 
 The repository includes an example skill for running `qli` without a global install and calling it from Python with `uv`:
@@ -374,6 +388,18 @@ qli context "How do I configure the API?"
 qli context "What changed in pricing?" --top-k 12 --max-chars 12000
 ```
 
+Serve the lexical index over HTTP:
+
+```bash
+qli serve
+qli serve --workspace ./docs/.kb --port 4000
+qli serve --workspace ./kbs --host 0.0.0.0 --port 4000
+```
+
+For a single workspace, use `POST /_search` or `POST /<configured-index-name>/_search`.
+For a directory of knowledge bases, use `POST /<directory-name>/_search`.
+The request body must be a Querylight JSON DSL object.
+
 ### Change Inspection
 
 ```bash

package/dist/cli/main.js

@@ -2,8 +2,8 @@
 
 // src/cli/run-cli.ts
 import { Command, Option } from "commander";
-import { readFile as readFile11, stat as stat4 } from "fs/promises";
-import path21 from "path";
+import { readFile as readFile11, stat as stat5 } from "fs/promises";
+import path22 from "path";
 
 // src/chunk/chunker.ts
 import { readFile as readFile3 } from "fs/promises";
@@ -53,7 +53,7 @@ var defaultConfig = () => ({
     defaultMode: "lexical",
     dense: {
       enabled: true,
-      modelId: "Xenova/all-MiniLM-L6-v2",
+      modelId: "Xenova/paraphrase-MiniLM-L3-v2",
       cacheDir: DEFAULT_SHARED_MODEL_CACHE_DIR,
       indexHashTables: 8,
       indexRandomSeed: 42,
@@ -61,7 +61,7 @@ var defaultConfig = () => ({
     },
     sparse: {
       enabled: true,
-      modelId: "opensearch-project/opensearch-neural-sparse-encoding-doc-v3-distill",
+      modelId: "opensearch-project/opensearch-neural-sparse-encoding-doc-v2-mini",
       cacheDir: DEFAULT_SHARED_MODEL_CACHE_DIR,
       documentTopTokens: 128,
       queryEncoding: "tokenizer-token-weights",
@@ -682,15 +682,26 @@ function createSparseChunkText(chunk) {
 // src/vector/dense.ts
 var denseEmbedderFactory = null;
 var EXACT_DENSE_RERANK_THRESHOLD = 5e3;
+function normalizeDenseEmbedder(embedder) {
+  if (typeof embedder === "function") {
+    return { embed: embedder };
+  }
+  return embedder;
+}
 async function createEmbedder(cacheDir, modelId) {
   if (denseEmbedderFactory) {
-    return denseEmbedderFactory(cacheDir, modelId);
+    return normalizeDenseEmbedder(await denseEmbedderFactory(cacheDir, modelId));
   }
   const runtime = await getDenseTransformersRuntime(cacheDir);
   const extractor = await runtime.pipeline("feature-extraction", modelId);
-  return async (text) => {
-    const output = await extractor(text, { pooling: "mean", normalize: true });
-    return output.tolist()[0];
+  return {
+    async embed(text) {
+      const output = await extractor(text, { pooling: "mean", normalize: true });
+      return output.tolist()[0];
+    },
+    async dispose() {
+      await extractor.dispose();
+    }
   };
 }
 function exactDenseQuery(payload, vector, topK) {
@@ -699,8 +710,12 @@ function exactDenseQuery(payload, vector, topK) {
 async function pullDenseModel(workspacePath, config) {
   const cacheDir = resolveCacheDir(workspacePath, config.cacheDir);
   await mkdir4(cacheDir, { recursive: true });
-  const embed = await createEmbedder(cacheDir, config.modelId);
-  await embed("warm dense model cache");
+  const embedder = await createEmbedder(cacheDir, config.modelId);
+  try {
+    await embedder.embed("warm dense model cache");
+  } finally {
+    await embedder.dispose?.();
+  }
 }
 async function buildDenseVectors({
   workspacePath,
@@ -710,53 +725,57 @@ async function buildDenseVectors({
   const chunks = await readJsonl(path8.join(workspacePath, "chunks", "chunks.jsonl"));
   const cacheDir = resolveCacheDir(workspacePath, config.cacheDir);
   await mkdir4(cacheDir, { recursive: true });
-  const embed = await createEmbedder(cacheDir, config.modelId);
-  const records = [];
-  let dimensions = 0;
-  reportProgress(progress, `Encoding ${chunks.length} chunk${chunks.length === 1 ? "" : "s"} for dense retrieval`);
-  for (const chunk of chunks) {
-    const embedding = await embed(createDenseChunkText(chunk));
-    dimensions ||= embedding.length;
-    records.push({
-      chunkId: chunk.id,
-      documentId: chunk.documentId,
-      sourceId: chunk.sourceId,
-      title: chunk.title,
-      uri: chunk.uri,
-      headingPath: chunk.headingPath,
-      text: chunk.text,
-      embedding
+  const embedder = await createEmbedder(cacheDir, config.modelId);
+  try {
+    const records = [];
+    let dimensions = 0;
+    reportProgress(progress, `Encoding ${chunks.length} chunk${chunks.length === 1 ? "" : "s"} for dense retrieval`);
+    for (const chunk of chunks) {
+      const embedding = await embedder.embed(createDenseChunkText(chunk));
+      dimensions ||= embedding.length;
+      records.push({
+        chunkId: chunk.id,
+        documentId: chunk.documentId,
+        sourceId: chunk.sourceId,
+        title: chunk.title,
+        uri: chunk.uri,
+        headingPath: chunk.headingPath,
+        text: chunk.text,
+        embedding
+      });
+      if (records.length === 1 || records.length % 100 === 0 || records.length === chunks.length) {
+        reportProgressDetail(progress, `Encoded ${records.length}/${chunks.length} chunks for dense retrieval`);
+      }
+    }
+    reportProgress(progress, "Building dense vector index");
+    const index = new VectorFieldIndex({
+      numHashTables: config.indexHashTables,
+      dimensions,
+      random: createSeededRandom(config.indexRandomSeed)
     });
-    if (records.length === 1 || records.length % 100 === 0 || records.length === chunks.length) {
-      reportProgressDetail(progress, `Encoded ${records.length}/${chunks.length} chunks for dense retrieval`);
+    for (const record of records) {
+      index.insert(record.chunkId, [record.embedding]);
     }
+    const metadata = {
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      modelId: config.modelId,
+      dimensions,
+      hashTables: config.indexHashTables,
+      randomSeed: config.indexRandomSeed,
+      chunkCount: records.length,
+      indexHash: sha256(JSON.stringify(index.indexState))
+    };
+    const payload = {
+      metadata,
+      indexState: index.indexState,
+      chunks: records
+    };
+    await writeDensePayload(workspacePath, payload);
+    reportProgress(progress, `Dense vectors written for ${records.length} chunk${records.length === 1 ? "" : "s"}`);
+    return payload;
+  } finally {
+    await embedder.dispose?.();
   }
-  reportProgress(progress, "Building dense vector index");
-  const index = new VectorFieldIndex({
-    numHashTables: config.indexHashTables,
-    dimensions,
-    random: createSeededRandom(config.indexRandomSeed)
-  });
-  for (const record of records) {
-    index.insert(record.chunkId, [record.embedding]);
-  }
-  const metadata = {
-    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-    modelId: config.modelId,
-    dimensions,
-    hashTables: config.indexHashTables,
-    randomSeed: config.indexRandomSeed,
-    chunkCount: records.length,
-    indexHash: sha256(JSON.stringify(index.indexState))
-  };
-  const payload = {
-    metadata,
-    indexState: index.indexState,
-    chunks: records
-  };
-  await writeDensePayload(workspacePath, payload);
-  reportProgress(progress, `Dense vectors written for ${records.length} chunk${records.length === 1 ? "" : "s"}`);
-  return payload;
 }
 async function denseQuery({
   workspacePath,
@@ -766,21 +785,25 @@ async function denseQuery({
 }) {
   const payload = await readDensePayload(workspacePath);
   const cacheDir = resolveCacheDir(workspacePath, config.cacheDir);
-  const embed = await createEmbedder(cacheDir, config.modelId);
-  const vector = await embed(query);
-  if (payload.chunks.length <= EXACT_DENSE_RERANK_THRESHOLD) {
+  const embedder = await createEmbedder(cacheDir, config.modelId);
+  try {
+    const vector = await embedder.embed(query);
+    if (payload.chunks.length <= EXACT_DENSE_RERANK_THRESHOLD) {
+      return exactDenseQuery(payload, vector, topK);
+    }
+    const index = new VectorFieldIndex({
+      numHashTables: payload.metadata.hashTables,
+      dimensions: payload.metadata.dimensions,
+      random: createSeededRandom(payload.metadata.randomSeed)
+    }).loadState(payload.indexState);
+    const approximateHits = index.query(vector, topK);
+    if (approximateHits.length >= topK) {
+      return approximateHits;
+    }
     return exactDenseQuery(payload, vector, topK);
+  } finally {
+    await embedder.dispose?.();
   }
-  const index = new VectorFieldIndex({
-    numHashTables: payload.metadata.hashTables,
-    dimensions: payload.metadata.dimensions,
-    random: createSeededRandom(payload.metadata.randomSeed)
-  }).loadState(payload.indexState);
-  const approximateHits = index.query(vector, topK);
-  if (approximateHits.length >= topK) {
-    return approximateHits;
-  }
-  return exactDenseQuery(payload, vector, topK);
 }
 
 // src/vector/sparse.ts
@@ -2173,13 +2196,17 @@ function isAllowed(url, baseUrl, includePatterns, excludePatterns, disallowRules
   if (url.search.length > 0) {
     return false;
   }
-  if (url.pathname.endsWith(".xml")) {
+  const pathname = url.pathname.toLowerCase();
+  if (pathname.endsWith(".xml")) {
     return false;
   }
-  if (url.pathname.includes("/cdn-cgi/")) {
+  if (pathname.endsWith(".pdf")) {
     return false;
   }
-  if (url.pathname === "/search" || url.pathname === "/search/" || url.pathname.endsWith("/search/")) {
+  if (pathname.includes("/cdn-cgi/")) {
+    return false;
+  }
+  if (pathname === "/search" || pathname === "/search/" || pathname.endsWith("/search/")) {
     return false;
   }
   if (disallowRules.some((rule) => rule !== "/" && url.pathname.startsWith(rule))) {
@@ -3203,13 +3230,20 @@ function searchResultsFromResponse(response2, showChunks = false) {
     metadata: hit._source.metadata
   }));
 }
+async function searchJsonRequest({
+  index,
+  request,
+  indexName = "querylight"
+}) {
+  return searchJsonDsl({ index, request, indexName });
+}
 async function searchJsonIndex({
   workspacePath,
   request,
   indexName = "querylight"
 }) {
   const index = await loadHydratedIndex(workspacePath);
-  return searchJsonDsl({ index, request, indexName });
+  return searchJsonRequest({ index, request, indexName });
 }
 function normalizeDisplayTitle(title) {
   return title.replace(/\s*\|\s*Querylight TS Demo\s*$/i, "").replace(/\s+/g, " ").trim();
@@ -3525,8 +3559,197 @@ async function searchIndex({
   return createSearchResponse(mode, finalHits, Date.now() - startedAt);
 }
 
-// src/query/related-service.ts
+// src/server/search-api.ts
+import { createServer } from "http";
+import { readdir, stat as stat4 } from "fs/promises";
 import path19 from "path";
+async function pathIsDirectory(candidatePath) {
+  try {
+    return (await stat4(candidatePath)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function discoverKnowledgeBases(workspacePath) {
+  try {
+    const singleWorkspace = await assertWorkspaceExists(workspacePath);
+    const config = await loadConfig(singleWorkspace);
+    const index = await loadHydratedIndex(singleWorkspace);
+    return {
+      mode: "single",
+      knowledgeBases: [{
+        name: config.index.name,
+        workspacePath: singleWorkspace,
+        configuredIndexName: config.index.name,
+        index
+      }]
+    };
+  } catch (error) {
+    if (!(error instanceof CliError) || error.code !== "WORKSPACE_ERROR") {
+      throw error;
+    }
+  }
+  const resolvedRoot = path19.resolve(workspacePath);
+  if (!await pathIsDirectory(resolvedRoot)) {
+    throw new CliError(`workspace path does not exist: ${resolvedRoot}`, "WORKSPACE_ERROR", 3 /* WorkspaceError */);
+  }
+  const entries = await readdir(resolvedRoot, { withFileTypes: true });
+  const knowledgeBases = (await Promise.all(entries.filter((entry) => entry.isDirectory()).map(async (entry) => {
+    const candidateWorkspace = path19.join(resolvedRoot, entry.name, ".kb");
+    try {
+      const workspace = await assertWorkspaceExists(candidateWorkspace);
+      const config = await loadConfig(workspace);
+      const index = await loadHydratedIndex(workspace);
+      return {
+        name: entry.name,
+        workspacePath: workspace,
+        configuredIndexName: config.index.name,
+        index
+      };
+    } catch (error) {
+      if (error instanceof CliError && error.code === "WORKSPACE_ERROR") {
+        return null;
+      }
+      throw error;
+    }
+  }))).filter((knowledgeBase) => knowledgeBase != null);
+  if (knowledgeBases.length === 0) {
+    throw new CliError(
+      `no knowledge bases found at ${resolvedRoot}; use a .kb workspace or a directory of named subdirectories that each contain .kb`,
+      "WORKSPACE_ERROR",
+      3 /* WorkspaceError */
+    );
+  }
+  return { mode: "multi", knowledgeBases };
+}
+function sendJson(response2, statusCode, payload) {
+  response2.statusCode = statusCode;
+  response2.setHeader("content-type", "application/json; charset=utf-8");
+  response2.end(JSON.stringify(payload));
+}
+function sendError(response2, statusCode, type, reason) {
+  sendJson(response2, statusCode, {
+    error: {
+      type,
+      reason
+    },
+    status: statusCode
+  });
+}
+async function readRequestBody(request) {
+  const chunks = [];
+  for await (const chunk of request) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+function parseSearchRequest(raw) {
+  const normalized = raw.trim();
+  if (normalized.length === 0) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(normalized);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("expected a JSON object");
+    }
+    return parsed;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new CliError(`invalid JSON request: ${message}`, "INVALID_ARGUMENT", 2 /* InvalidArguments */);
+  }
+}
+function routeForKnowledgeBase(mode, knowledgeBase) {
+  return mode === "single" ? "/_search" : `/${knowledgeBase.name}/_search`;
+}
+function resolveKnowledgeBaseForPath(pathname, mode, knowledgeBases) {
+  const segments = pathname.split("/").filter(Boolean);
+  if (mode === "single") {
+    const knowledgeBase = [...knowledgeBases.values()][0];
+    if (!knowledgeBase) {
+      return null;
+    }
+    if (segments.length === 1 && segments[0] === "_search") {
+      return knowledgeBase;
+    }
+    if (segments.length === 2 && segments[1] === "_search" && segments[0] === knowledgeBase.configuredIndexName) {
+      return knowledgeBase;
+    }
+    return null;
+  }
+  if (segments.length === 2 && segments[1] === "_search") {
+    return knowledgeBases.get(segments[0]) ?? null;
+  }
+  return null;
+}
+async function handleSearchRequest(request, response2, pathname, mode, knowledgeBases) {
+  if (request.method !== "GET" && request.method !== "POST") {
+    response2.setHeader("allow", "GET, POST");
+    sendError(response2, 405, "method_not_allowed", `unsupported method for ${pathname}`);
+    return;
+  }
+  const knowledgeBase = resolveKnowledgeBaseForPath(pathname, mode, knowledgeBases);
+  if (!knowledgeBase) {
+    sendError(response2, 404, "resource_not_found_exception", `unknown search route: ${pathname}`);
+    return;
+  }
+  try {
+    const requestBody = parseSearchRequest(await readRequestBody(request));
+    const indexName = mode === "multi" ? knowledgeBase.name : knowledgeBase.configuredIndexName;
+    const result = await searchJsonRequest({
+      index: knowledgeBase.index,
+      request: requestBody,
+      indexName
+    });
+    sendJson(response2, 200, result);
+  } catch (error) {
+    if (error instanceof CliError && error.code === "INVALID_ARGUMENT") {
+      sendError(response2, 400, "parse_exception", error.message);
+      return;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    sendError(response2, 500, "search_phase_execution_exception", message);
+  }
+}
+async function startSearchApiServer({
+  workspacePath,
+  host = "127.0.0.1",
+  port = 3e3
+}) {
+  const { mode, knowledgeBases } = await discoverKnowledgeBases(workspacePath);
+  const byName = new Map(knowledgeBases.map((knowledgeBase) => [knowledgeBase.name, knowledgeBase]));
+  const server = createServer(async (request, response2) => {
+    const url2 = new URL(request.url ?? "/", `http://${request.headers.host ?? `${host}:${port}`}`);
+    await handleSearchRequest(request, response2, url2.pathname, mode, byName);
+  });
+  await new Promise((resolve2, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, () => {
+      server.off("error", reject);
+      resolve2();
+    });
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    throw new CliError("server failed to bind to a TCP address", "SERVER_ERROR", 1 /* GeneralError */);
+  }
+  const url = `http://${host}:${address.port}`;
+  return {
+    mode,
+    url,
+    knowledgeBases: knowledgeBases.map((knowledgeBase) => ({
+      name: knowledgeBase.name,
+      workspacePath: knowledgeBase.workspacePath,
+      route: routeForKnowledgeBase(mode, knowledgeBase)
+    })),
+    close: async () => new Promise((resolve2, reject) => {
+      server.close((error) => error ? reject(error) : resolve2());
+    })
+  };
+}
+
+// src/query/related-service.ts
+import path20 from "path";
 function cosineSimilarity2(left, right) {
   let dot = 0;
   let leftNorm = 0;
@@ -3602,7 +3825,7 @@ async function findRelatedDocuments({
   if (!await fileExists(denseVectorPath(workspacePath))) {
     throw new CliError("dense vector index is not built; run `qli models pull --dense` and `qli rebuild`", "DENSE_INDEX_MISSING", 7 /* QueryError */);
   }
-  const documents = await readJsonl(path19.join(workspacePath, "documents", "documents.jsonl"));
+  const documents = await readJsonl(path20.join(workspacePath, "documents", "documents.jsonl"));
   const selected = resolveDocumentSelector(documents, document);
   const densePayload = await readDensePayload(workspacePath);
   const vectors = buildDocumentVectors(documents, densePayload.chunks, densePayload.metadata.dimensions);
@@ -3675,7 +3898,7 @@ async function createContext({
 }
 
 // src/report/diff-service.ts
-import path20 from "path";
+import path21 from "path";
 function chooseBaselineRun(runs, since) {
   if (since === "last-run") {
     return runs.at(-1);
@@ -3691,7 +3914,7 @@ async function diffWorkspace({
   documentId,
   since
 }) {
-  const current = await readJsonl(path20.join(workspacePath, "documents", "documents.jsonl"));
+  const current = await readJsonl(path21.join(workspacePath, "documents", "documents.jsonl"));
   const baseline = chooseBaselineRun(await listRuns(workspacePath), since);
   const previous = new Map((baseline?.documentsSnapshot ?? []).map((document) => [document.id, document]));
   const changedDocuments = current.filter((document) => (!sourceId || document.sourceId === sourceId) && (!documentId || document.id === documentId)).filter((document) => {
@@ -4050,7 +4273,7 @@ function parseDateValue(input, optionName) {
   return parsed.toISOString();
 }
 async function parseJsonArgument(input) {
-  const raw = input.startsWith("@") ? await readFile11(path21.resolve(input.slice(1)), "utf8") : input;
+  const raw = input.startsWith("@") ? await readFile11(path22.resolve(input.slice(1)), "utf8") : input;
   try {
     const parsed = JSON.parse(raw);
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
@@ -4094,14 +4317,14 @@ function searchDateRanges(options) {
   return entries;
 }
 async function resolveWorkspace(options) {
-  return path21.resolve(options.workspace ?? DEFAULT_WORKSPACE);
+  return path22.resolve(options.workspace ?? DEFAULT_WORKSPACE);
 }
 function workspaceFromArgv(argv) {
   const index = argv.findIndex((arg) => arg === "--workspace");
   if (index >= 0 && argv[index + 1]) {
-    return path21.resolve(argv[index + 1]);
+    return path22.resolve(argv[index + 1]);
   }
-  return path21.resolve(DEFAULT_WORKSPACE);
+  return path22.resolve(DEFAULT_WORKSPACE);
 }
 async function runCli(argv, io = {}) {
   const capture = { stdout: [], stderr: [], ...io };
@@ -4195,7 +4418,7 @@ Notes:
     }
     const stored = await addSource(workspace, {
       type,
-      uri: ["file", "directory"].includes(type) ? path21.resolve(uri) : uri,
+      uri: ["file", "directory"].includes(type) ? path22.resolve(uri) : uri,
       name: options.name,
       enabled: true,
       tags: options.tag ?? [],
@@ -4459,6 +4682,63 @@ Notes:
     });
     emit(global.json, capture, response("search-json", workspace, result), JSON.stringify(result, null, 2));
   });
+  program.command("serve").description("Start a small HTTP API that exposes Querylight JSON DSL search through an OpenSearch-like _search endpoint.").option("--host <host>", "Host interface to bind. Defaults to 127.0.0.1.", "127.0.0.1").option("--port <n>", "Port to bind. Use 0 to let the OS choose a free port.", "3000").addHelpText("after", `
+Examples:
+  qli serve
+  qli serve --workspace ./docs/.kb --port 4000
+  qli serve --workspace ./kbs --host 0.0.0.0 --port 4000
+
+Routes:
+  Single workspace: POST /_search
+  Single workspace: POST /<configured-index-name>/_search
+  Multi-KB root: POST /<directory-name>/_search
+
+Notes:
+  The request body must be a Querylight JSON DSL object.
+  serve only exposes lexical _search for now.
+  When --workspace points to a directory of knowledge bases, each child directory must contain its own .kb workspace.
+  Index files are loaded once at startup and reused across requests.`).action(async function command(options) {
+    const global = this.optsWithGlobals();
+    const workspace = await resolveWorkspace({ workspace: global.workspace });
+    const port = Number(options.port);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+      throw new CliError(`invalid port: ${options.port}`, "INVALID_ARGUMENT", 2 /* InvalidArguments */);
+    }
+    const server = await startSearchApiServer({
+      workspacePath: workspace,
+      host: options.host,
+      port
+    });
+    const data = {
+      url: server.url,
+      mode: server.mode,
+      knowledgeBases: server.knowledgeBases
+    };
+    const human = [
+      `Listening on ${server.url}`,
+      ...server.knowledgeBases.map((knowledgeBase) => `${knowledgeBase.route} -> ${knowledgeBase.workspacePath}`)
+    ].join("\n");
+    emit(global.json, capture, response("serve", workspace, data), human);
+    const shutdown = async () => {
+      for (const signal of ["SIGINT", "SIGTERM"]) {
+        process.off(signal, stop);
+      }
+      await server.close();
+    };
+    const stop = () => {
+      void shutdown().then(() => resolveStop(), rejectStop);
+    };
+    let resolveStop;
+    let rejectStop;
+    const waitForStop = new Promise((resolve2, reject) => {
+      resolveStop = resolve2;
+      rejectStop = reject;
+    });
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+      process.once(signal, stop);
+    }
+    await waitForStop;
+  });
   program.command("related").description("Find documents similar to an existing document by id or URI.").argument("<document>", "Document id, uri, or canonical uri").option("--top-k <n>", "Maximum number of related documents to return.", "12").addHelpText("after", `
 Examples:
   qli related doc_123
@@ -4582,7 +4862,7 @@ Examples:
     try {
       const meta = await readLatestIndexMetadata(workspace);
       latestIndex = meta.createdAt;
-      indexSize = (await stat4(await resolveLatestIndexArtifactPath(workspace))).size;
+      indexSize = (await stat5(await resolveLatestIndexArtifactPath(workspace))).size;
     } catch {
       latestIndex = void 0;
     }

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from "./ingest/ingest-service.js";
 export * from "./chunk/chunker.js";
 export * from "./index/querylight-indexer.js";
 export * from "./query/search-service.js";
+export * from "./server/search-api.js";
 export * from "./query/related-service.js";
 export * from "./query/context-builder.js";
 export * from "./report/diff-service.js";

package/dist/index.js

@@ -57,7 +57,7 @@ var defaultConfig = () => ({
     defaultMode: "lexical",
     dense: {
       enabled: true,
-      modelId: "Xenova/all-MiniLM-L6-v2",
+      modelId: "Xenova/paraphrase-MiniLM-L3-v2",
       cacheDir: DEFAULT_SHARED_MODEL_CACHE_DIR,
       indexHashTables: 8,
       indexRandomSeed: 42,
@@ -65,7 +65,7 @@ var defaultConfig = () => ({
     },
     sparse: {
       enabled: true,
-      modelId: "opensearch-project/opensearch-neural-sparse-encoding-doc-v3-distill",
+      modelId: "opensearch-project/opensearch-neural-sparse-encoding-doc-v2-mini",
       cacheDir: DEFAULT_SHARED_MODEL_CACHE_DIR,
       documentTopTokens: 128,
       queryEncoding: "tokenizer-token-weights",
@@ -1213,13 +1213,17 @@ function isAllowed(url, baseUrl, includePatterns, excludePatterns, disallowRules
   if (url.search.length > 0) {
     return false;
   }
-  if (url.pathname.endsWith(".xml")) {
+  const pathname = url.pathname.toLowerCase();
+  if (pathname.endsWith(".xml")) {
     return false;
   }
-  if (url.pathname.includes("/cdn-cgi/")) {
+  if (pathname.endsWith(".pdf")) {
     return false;
   }
-  if (url.pathname === "/search" || url.pathname === "/search/" || url.pathname.endsWith("/search/")) {
+  if (pathname.includes("/cdn-cgi/")) {
+    return false;
+  }
+  if (pathname === "/search" || pathname === "/search/" || pathname.endsWith("/search/")) {
     return false;
   }
   if (disallowRules.some((rule) => rule !== "/" && url.pathname.startsWith(rule))) {
@@ -2058,15 +2062,26 @@ function createSparseChunkText(chunk) {
 // src/vector/dense.ts
 var denseEmbedderFactory = null;
 var EXACT_DENSE_RERANK_THRESHOLD = 5e3;
+function normalizeDenseEmbedder(embedder) {
+  if (typeof embedder === "function") {
+    return { embed: embedder };
+  }
+  return embedder;
+}
 async function createEmbedder(cacheDir, modelId) {
   if (denseEmbedderFactory) {
-    return denseEmbedderFactory(cacheDir, modelId);
+    return normalizeDenseEmbedder(await denseEmbedderFactory(cacheDir, modelId));
   }
   const runtime = await getDenseTransformersRuntime(cacheDir);
   const extractor = await runtime.pipeline("feature-extraction", modelId);
-  return async (text) => {
-    const output = await extractor(text, { pooling: "mean", normalize: true });
-    return output.tolist()[0];
+  return {
+    async embed(text) {
+      const output = await extractor(text, { pooling: "mean", normalize: true });
+      return output.tolist()[0];
+    },
+    async dispose() {
+      await extractor.dispose();
+    }
   };
 }
 function exactDenseQuery(payload, vector, topK) {
@@ -2080,53 +2095,57 @@ async function buildDenseVectors({
   const chunks = await readJsonl(path14.join(workspacePath, "chunks", "chunks.jsonl"));
   const cacheDir = resolveCacheDir(workspacePath, config.cacheDir);
   await mkdir7(cacheDir, { recursive: true });
-  const embed = await createEmbedder(cacheDir, config.modelId);
-  const records = [];
-  let dimensions = 0;
-  reportProgress(progress, `Encoding ${chunks.length} chunk${chunks.length === 1 ? "" : "s"} for dense retrieval`);
-  for (const chunk of chunks) {
-    const embedding = await embed(createDenseChunkText(chunk));
-    dimensions ||= embedding.length;
-    records.push({
-      chunkId: chunk.id,
-      documentId: chunk.documentId,
-      sourceId: chunk.sourceId,
-      title: chunk.title,
-      uri: chunk.uri,
-      headingPath: chunk.headingPath,
-      text: chunk.text,
-      embedding
-    });
-    if (records.length === 1 || records.length % 100 === 0 || records.length === chunks.length) {
-      reportProgressDetail(progress, `Encoded ${records.length}/${chunks.length} chunks for dense retrieval`);
+  const embedder = await createEmbedder(cacheDir, config.modelId);
+  try {
+    const records = [];
+    let dimensions = 0;
+    reportProgress(progress, `Encoding ${chunks.length} chunk${chunks.length === 1 ? "" : "s"} for dense retrieval`);
+    for (const chunk of chunks) {
+      const embedding = await embedder.embed(createDenseChunkText(chunk));
+      dimensions ||= embedding.length;
+      records.push({
+        chunkId: chunk.id,
+        documentId: chunk.documentId,
+        sourceId: chunk.sourceId,
+        title: chunk.title,
+        uri: chunk.uri,
+        headingPath: chunk.headingPath,
+        text: chunk.text,
+        embedding
+      });
+      if (records.length === 1 || records.length % 100 === 0 || records.length === chunks.length) {
+        reportProgressDetail(progress, `Encoded ${records.length}/${chunks.length} chunks for dense retrieval`);
+      }
     }
+    reportProgress(progress, "Building dense vector index");
+    const index = new VectorFieldIndex({
+      numHashTables: config.indexHashTables,
+      dimensions,
+      random: createSeededRandom(config.indexRandomSeed)
+    });
+    for (const record of records) {
+      index.insert(record.chunkId, [record.embedding]);
+    }
+    const metadata = {
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      modelId: config.modelId,
+      dimensions,
+      hashTables: config.indexHashTables,
+      randomSeed: config.indexRandomSeed,
+      chunkCount: records.length,
+      indexHash: sha256(JSON.stringify(index.indexState))
+    };
+    const payload = {
+      metadata,
+      indexState: index.indexState,
+      chunks: records
+    };
+    await writeDensePayload(workspacePath, payload);
+    reportProgress(progress, `Dense vectors written for ${records.length} chunk${records.length === 1 ? "" : "s"}`);
+    return payload;
+  } finally {
+    await embedder.dispose?.();
   }
-  reportProgress(progress, "Building dense vector index");
-  const index = new VectorFieldIndex({
-    numHashTables: config.indexHashTables,
-    dimensions,
-    random: createSeededRandom(config.indexRandomSeed)
-  });
-  for (const record of records) {
-    index.insert(record.chunkId, [record.embedding]);
-  }
-  const metadata = {
-    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-    modelId: config.modelId,
-    dimensions,
-    hashTables: config.indexHashTables,
-    randomSeed: config.indexRandomSeed,
-    chunkCount: records.length,
-    indexHash: sha256(JSON.stringify(index.indexState))
-  };
-  const payload = {
-    metadata,
-    indexState: index.indexState,
-    chunks: records
-  };
-  await writeDensePayload(workspacePath, payload);
-  reportProgress(progress, `Dense vectors written for ${records.length} chunk${records.length === 1 ? "" : "s"}`);
-  return payload;
 }
 async function denseQuery({
   workspacePath,
@@ -2136,21 +2155,25 @@ async function denseQuery({
 }) {
   const payload = await readDensePayload(workspacePath);
   const cacheDir = resolveCacheDir(workspacePath, config.cacheDir);
-  const embed = await createEmbedder(cacheDir, config.modelId);
-  const vector = await embed(query);
-  if (payload.chunks.length <= EXACT_DENSE_RERANK_THRESHOLD) {
+  const embedder = await createEmbedder(cacheDir, config.modelId);
+  try {
+    const vector = await embedder.embed(query);
+    if (payload.chunks.length <= EXACT_DENSE_RERANK_THRESHOLD) {
+      return exactDenseQuery(payload, vector, topK);
+    }
+    const index = new VectorFieldIndex({
+      numHashTables: payload.metadata.hashTables,
+      dimensions: payload.metadata.dimensions,
+      random: createSeededRandom(payload.metadata.randomSeed)
+    }).loadState(payload.indexState);
+    const approximateHits = index.query(vector, topK);
+    if (approximateHits.length >= topK) {
+      return approximateHits;
+    }
     return exactDenseQuery(payload, vector, topK);
+  } finally {
+    await embedder.dispose?.();
   }
-  const index = new VectorFieldIndex({
-    numHashTables: payload.metadata.hashTables,
-    dimensions: payload.metadata.dimensions,
-    random: createSeededRandom(payload.metadata.randomSeed)
-  }).loadState(payload.indexState);
-  const approximateHits = index.query(vector, topK);
-  if (approximateHits.length >= topK) {
-    return approximateHits;
-  }
-  return exactDenseQuery(payload, vector, topK);
 }
 
 // src/vector/sparse.ts
@@ -2894,13 +2917,20 @@ function searchResultsFromResponse(response, showChunks = false) {
     metadata: hit._source.metadata
   }));
 }
+async function searchJsonRequest({
+  index,
+  request,
+  indexName = "querylight"
+}) {
+  return searchJsonDsl({ index, request, indexName });
+}
 async function searchJsonIndex({
   workspacePath,
   request,
   indexName = "querylight"
 }) {
   const index = await loadHydratedIndex(workspacePath);
-  return searchJsonDsl({ index, request, indexName });
+  return searchJsonRequest({ index, request, indexName });
 }
 function normalizeDisplayTitle(title) {
   return title.replace(/\s*\|\s*Querylight TS Demo\s*$/i, "").replace(/\s+/g, " ").trim();
@@ -3216,8 +3246,197 @@ async function searchIndex({
   return createSearchResponse(mode, finalHits, Date.now() - startedAt);
 }
 
-// src/query/related-service.ts
+// src/server/search-api.ts
+import { createServer } from "http";
+import { readdir, stat as stat4 } from "fs/promises";
 import path19 from "path";
+async function pathIsDirectory(candidatePath) {
+  try {
+    return (await stat4(candidatePath)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function discoverKnowledgeBases(workspacePath) {
+  try {
+    const singleWorkspace = await assertWorkspaceExists(workspacePath);
+    const config = await loadConfig(singleWorkspace);
+    const index = await loadHydratedIndex(singleWorkspace);
+    return {
+      mode: "single",
+      knowledgeBases: [{
+        name: config.index.name,
+        workspacePath: singleWorkspace,
+        configuredIndexName: config.index.name,
+        index
+      }]
+    };
+  } catch (error) {
+    if (!(error instanceof CliError) || error.code !== "WORKSPACE_ERROR") {
+      throw error;
+    }
+  }
+  const resolvedRoot = path19.resolve(workspacePath);
+  if (!await pathIsDirectory(resolvedRoot)) {
+    throw new CliError(`workspace path does not exist: ${resolvedRoot}`, "WORKSPACE_ERROR", 3 /* WorkspaceError */);
+  }
+  const entries = await readdir(resolvedRoot, { withFileTypes: true });
+  const knowledgeBases = (await Promise.all(entries.filter((entry) => entry.isDirectory()).map(async (entry) => {
+    const candidateWorkspace = path19.join(resolvedRoot, entry.name, ".kb");
+    try {
+      const workspace = await assertWorkspaceExists(candidateWorkspace);
+      const config = await loadConfig(workspace);
+      const index = await loadHydratedIndex(workspace);
+      return {
+        name: entry.name,
+        workspacePath: workspace,
+        configuredIndexName: config.index.name,
+        index
+      };
+    } catch (error) {
+      if (error instanceof CliError && error.code === "WORKSPACE_ERROR") {
+        return null;
+      }
+      throw error;
+    }
+  }))).filter((knowledgeBase) => knowledgeBase != null);
+  if (knowledgeBases.length === 0) {
+    throw new CliError(
+      `no knowledge bases found at ${resolvedRoot}; use a .kb workspace or a directory of named subdirectories that each contain .kb`,
+      "WORKSPACE_ERROR",
+      3 /* WorkspaceError */
+    );
+  }
+  return { mode: "multi", knowledgeBases };
+}
+function sendJson(response, statusCode, payload) {
+  response.statusCode = statusCode;
+  response.setHeader("content-type", "application/json; charset=utf-8");
+  response.end(JSON.stringify(payload));
+}
+function sendError(response, statusCode, type, reason) {
+  sendJson(response, statusCode, {
+    error: {
+      type,
+      reason
+    },
+    status: statusCode
+  });
+}
+async function readRequestBody(request) {
+  const chunks = [];
+  for await (const chunk of request) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+function parseSearchRequest(raw) {
+  const normalized = raw.trim();
+  if (normalized.length === 0) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(normalized);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("expected a JSON object");
+    }
+    return parsed;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new CliError(`invalid JSON request: ${message}`, "INVALID_ARGUMENT", 2 /* InvalidArguments */);
+  }
+}
+function routeForKnowledgeBase(mode, knowledgeBase) {
+  return mode === "single" ? "/_search" : `/${knowledgeBase.name}/_search`;
+}
+function resolveKnowledgeBaseForPath(pathname, mode, knowledgeBases) {
+  const segments = pathname.split("/").filter(Boolean);
+  if (mode === "single") {
+    const knowledgeBase = [...knowledgeBases.values()][0];
+    if (!knowledgeBase) {
+      return null;
+    }
+    if (segments.length === 1 && segments[0] === "_search") {
+      return knowledgeBase;
+    }
+    if (segments.length === 2 && segments[1] === "_search" && segments[0] === knowledgeBase.configuredIndexName) {
+      return knowledgeBase;
+    }
+    return null;
+  }
+  if (segments.length === 2 && segments[1] === "_search") {
+    return knowledgeBases.get(segments[0]) ?? null;
+  }
+  return null;
+}
+async function handleSearchRequest(request, response, pathname, mode, knowledgeBases) {
+  if (request.method !== "GET" && request.method !== "POST") {
+    response.setHeader("allow", "GET, POST");
+    sendError(response, 405, "method_not_allowed", `unsupported method for ${pathname}`);
+    return;
+  }
+  const knowledgeBase = resolveKnowledgeBaseForPath(pathname, mode, knowledgeBases);
+  if (!knowledgeBase) {
+    sendError(response, 404, "resource_not_found_exception", `unknown search route: ${pathname}`);
+    return;
+  }
+  try {
+    const requestBody = parseSearchRequest(await readRequestBody(request));
+    const indexName = mode === "multi" ? knowledgeBase.name : knowledgeBase.configuredIndexName;
+    const result = await searchJsonRequest({
+      index: knowledgeBase.index,
+      request: requestBody,
+      indexName
+    });
+    sendJson(response, 200, result);
+  } catch (error) {
+    if (error instanceof CliError && error.code === "INVALID_ARGUMENT") {
+      sendError(response, 400, "parse_exception", error.message);
+      return;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    sendError(response, 500, "search_phase_execution_exception", message);
+  }
+}
+async function startSearchApiServer({
+  workspacePath,
+  host = "127.0.0.1",
+  port = 3e3
+}) {
+  const { mode, knowledgeBases } = await discoverKnowledgeBases(workspacePath);
+  const byName = new Map(knowledgeBases.map((knowledgeBase) => [knowledgeBase.name, knowledgeBase]));
+  const server = createServer(async (request, response) => {
+    const url2 = new URL(request.url ?? "/", `http://${request.headers.host ?? `${host}:${port}`}`);
+    await handleSearchRequest(request, response, url2.pathname, mode, byName);
+  });
+  await new Promise((resolve2, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, () => {
+      server.off("error", reject);
+      resolve2();
+    });
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    throw new CliError("server failed to bind to a TCP address", "SERVER_ERROR", 1 /* GeneralError */);
+  }
+  const url = `http://${host}:${address.port}`;
+  return {
+    mode,
+    url,
+    knowledgeBases: knowledgeBases.map((knowledgeBase) => ({
+      name: knowledgeBase.name,
+      workspacePath: knowledgeBase.workspacePath,
+      route: routeForKnowledgeBase(mode, knowledgeBase)
+    })),
+    close: async () => new Promise((resolve2, reject) => {
+      server.close((error) => error ? reject(error) : resolve2());
+    })
+  };
+}
+
+// src/query/related-service.ts
+import path20 from "path";
 function cosineSimilarity2(left, right) {
   let dot = 0;
   let leftNorm = 0;
@@ -3293,7 +3512,7 @@ async function findRelatedDocuments({
   if (!await fileExists(denseVectorPath(workspacePath))) {
     throw new CliError("dense vector index is not built; run `qli models pull --dense` and `qli rebuild`", "DENSE_INDEX_MISSING", 7 /* QueryError */);
   }
-  const documents = await readJsonl(path19.join(workspacePath, "documents", "documents.jsonl"));
+  const documents = await readJsonl(path20.join(workspacePath, "documents", "documents.jsonl"));
   const selected = resolveDocumentSelector(documents, document);
   const densePayload = await readDensePayload(workspacePath);
   const vectors = buildDocumentVectors(documents, densePayload.chunks, densePayload.metadata.dimensions);
@@ -3366,7 +3585,7 @@ async function createContext({
 }
 
 // src/report/diff-service.ts
-import path20 from "path";
+import path21 from "path";
 function chooseBaselineRun(runs, since) {
   if (since === "last-run") {
     return runs.at(-1);
@@ -3382,7 +3601,7 @@ async function diffWorkspace({
   documentId,
   since
 }) {
-  const current = await readJsonl(path20.join(workspacePath, "documents", "documents.jsonl"));
+  const current = await readJsonl(path21.join(workspacePath, "documents", "documents.jsonl"));
   const baseline = chooseBaselineRun(await listRuns(workspacePath), since);
   const previous = new Map((baseline?.documentsSnapshot ?? []).map((document) => [document.id, document]));
   const changedDocuments = current.filter((document) => (!sourceId || document.sourceId === sourceId) && (!documentId || document.id === documentId)).filter((document) => {
@@ -3438,12 +3657,15 @@ export {
   ingestSources,
   listSources,
   loadConfig,
+  loadHydratedIndex,
   removeSource,
   renderChangeReport,
   reprocessDocuments,
   searchIndex,
   searchJsonIndex,
+  searchJsonRequest,
   searchResultsFromResponse,
+  startSearchApiServer,
   updateSource,
   writeDefaultConfig
 };

package/dist/query/search-service.d.ts

@@ -1,5 +1,6 @@
-import { type JsonDslRequest, type JsonDslResponse } from "@tryformation/querylight-ts";
+import { type DocumentIndex, type JsonDslRequest, type JsonDslResponse } from "@tryformation/querylight-ts";
 import type { RetrievalMode, SearchResponseData, SearchResult } from "../types/models.js";
+export declare function loadHydratedIndex(workspacePath: string): Promise<DocumentIndex>;
 type SearchDateField = "publicationDate" | "firstSeenAt" | "lastSeenAt" | "lastChangedAt" | "crawledAt";
 type SearchDateRange = {
     field: SearchDateField;
@@ -7,6 +8,11 @@ type SearchDateRange = {
     to?: string;
 };
 export declare function searchResultsFromResponse(response: SearchResponseData, showChunks?: boolean): SearchResult[];
+export declare function searchJsonRequest({ index, request, indexName }: {
+    index: DocumentIndex;
+    request: JsonDslRequest;
+    indexName?: string;
+}): Promise<JsonDslResponse>;
 export declare function searchJsonIndex({ workspacePath, request, indexName }: {
     workspacePath: string;
     request: JsonDslRequest;

package/dist/server/search-api.d.ts

@@ -0,0 +1,15 @@
+export type SearchApiServerInfo = {
+    mode: "single" | "multi";
+    url: string;
+    knowledgeBases: Array<{
+        name: string;
+        workspacePath: string;
+        route: string;
+    }>;
+    close: () => Promise<void>;
+};
+export declare function startSearchApiServer({ workspacePath, host, port }: {
+    workspacePath: string;
+    host?: string;
+    port?: number;
+}): Promise<SearchApiServerInfo>;

package/dist/vector/dense.d.ts

@@ -1,6 +1,10 @@
 import { type ProgressHandler } from "../core/progress.js";
 import type { DenseVectorPayload, WorkspaceConfig } from "../types/models.js";
-export declare function setDenseEmbedderFactoryForTests(factory: ((cacheDir: string, modelId: string) => Promise<(text: string) => Promise<number[]>>) | null): void;
+type DenseEmbedder = {
+    embed(text: string): Promise<number[]>;
+    dispose?: () => Promise<void>;
+};
+export declare function setDenseEmbedderFactoryForTests(factory: ((cacheDir: string, modelId: string) => Promise<DenseEmbedder | ((text: string) => Promise<number[]>)>) | null): void;
 export declare function pullDenseModel(workspacePath: string, config: WorkspaceConfig["retrieval"]["dense"]): Promise<void>;
 export declare function buildDenseVectors({ workspacePath, config, progress }: {
     workspacePath: string;
@@ -13,3 +17,4 @@ export declare function denseQuery({ workspacePath, config, query, topK }: {
     query: string;
     topK: number;
 }): Promise<Array<[string, number]>>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryformation/querylight-cli",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Querylight CLI for building and querying local knowledge bases.",
   "license": "MIT",
   "homepage": "https://github.com/formation-res/querylight-cli#readme",

package/scripts/sparse-encode.py

@@ -7,19 +7,40 @@ from huggingface_hub import hf_hub_download
 from transformers import AutoModelForMaskedLM, AutoTokenizer
 
 
+def _load_query_weights_file(model_id: str, filename: str):
+    try:
+        return hf_hub_download(repo_id=model_id, filename=filename)
+    except Exception:
+        return None
+
+
 def build_query_token_weight_vector(tokenizer, model_id: str):
-    local_cached_path = hf_hub_download(repo_id=model_id, filename="query_token_weights.txt")
     vector = [0.0] * tokenizer.vocab_size
-
-    with open(local_cached_path, encoding="utf-8") as handle:
-        for line in handle:
-            line = line.rstrip("\n")
-            if not line:
-                continue
-            token, weight = line.split("\t", 1)
+    local_cached_path = _load_query_weights_file(model_id, "query_token_weights.txt")
+
+    if local_cached_path is not None:
+        with open(local_cached_path, encoding="utf-8") as handle:
+            for line in handle:
+                line = line.rstrip("\n")
+                if not line:
+                    continue
+                token, weight = line.split("\t", 1)
+                token_id = tokenizer._convert_token_to_id_with_added_voc(token)
+                if token_id is not None and token_id >= 0:
+                    vector[token_id] = float(weight)
+        return vector
+
+    local_cached_path = _load_query_weights_file(model_id, "idf.json")
+    if local_cached_path is not None:
+        with open(local_cached_path, encoding="utf-8") as handle:
+            idf = json.load(handle)
+        for token, weight in idf.items():
             token_id = tokenizer._convert_token_to_id_with_added_voc(token)
             if token_id is not None and token_id >= 0:
                 vector[token_id] = float(weight)
+        return vector
+
+    raise FileNotFoundError(f"missing query token weights for {model_id}: expected query_token_weights.txt or idf.json")
 
     return vector