@madewithremy/admin 0.1.30 → 0.1.31

package/dist/prod.js

@@ -36,10 +36,10 @@ function fatal(message) {
   throw new CliError(message);
 }
 var AdminApiError = class extends Error {
-  constructor(method, path7, status2, body) {
-    super(`API ${method} ${path7} returned ${status2}: ${JSON.stringify(body)}`);
+  constructor(method, path8, status2, body) {
+    super(`API ${method} ${path8} returned ${status2}: ${JSON.stringify(body)}`);
     this.method = method;
-    this.path = path7;
+    this.path = path8;
     this.status = status2;
     this.body = body;
     this.name = "AdminApiError";
@@ -1036,6 +1036,13 @@ function summarizeRelease(release) {
     publishedAt: release.publishedAt ?? null,
     ...release.previewUrl ? { previewUrl: release.previewUrl } : {}
   };
+  const readers = (release.dataSources ?? []).filter((d) => d.reader);
+  if (readers.length > 0 && release.status === "live") {
+    summary2.readers = readers.map((d) => ({
+      slug: d.slug,
+      unread: d.readerUnread ?? 0
+    }));
+  }
   if (release.status !== "failed") {
     return summary2;
   }
@@ -3092,8 +3099,8 @@ Notes:
   - Public image URLs accept transform params, e.g. ?w=400&fit=cover.`;
 
 // src/commands/dataSources.ts
-import fs5 from "fs";
-import path5 from "path";
+import fs6 from "fs";
+import path6 from "path";
 
 // src/ops/dataSources.ts
 import { createHash as createHash2 } from "crypto";
@@ -3111,7 +3118,7 @@ var summarize = (d) => ({
   ...d.errorMessage ? { error: d.errorMessage } : {}
 });
 async function addDocument(ctx, params) {
-  const { slug, filename, content, metadata, onProgress } = params;
+  const { slug, filename, content, metadata, entities: entities2, onProgress } = params;
   const contentHash = createHash2("sha256").update(content).digest("hex");
   const token = await call(
     ctx,
@@ -3121,7 +3128,8 @@ async function addDocument(ctx, params) {
       slug,
       filename,
       contentHash,
-      ...metadata ? { metadata } : {}
+      ...metadata ? { metadata } : {},
+      ...entities2 ? { entities: entities2 } : {}
     }
   );
   if (token.alreadyCurrent) {
@@ -3147,7 +3155,8 @@ async function addDocument(ctx, params) {
       contentHash,
       contentType: token.contentType,
       size: content.length,
-      ...metadata ? { metadata } : {}
+      ...metadata ? { metadata } : {},
+      ...entities2 ? { entities: entities2 } : {}
     }
   );
   return {
@@ -3324,6 +3333,20 @@ function count(ctx, params) {
     ...candidate ? { candidate: true } : {}
   });
 }
+function entities(ctx, params) {
+  const { slug, filter, limit, candidate } = params;
+  return call(
+    ctx,
+    "POST",
+    `${base(ctx.appId)}/entities`,
+    {
+      slug,
+      ...filter ? { filter } : {},
+      ...limit !== void 0 ? { limit } : {},
+      ...candidate ? { candidate: true } : {}
+    }
+  );
+}
 function configGet(ctx, slug) {
   return call(
     ctx,
@@ -3485,6 +3508,67 @@ function deleteSource(ctx, slug) {
     { slug }
   );
 }
+var DICTIONARY_PAGE_ENTRIES = 1e4;
+var DICTIONARY_PAGE_BYTES = 4e6;
+async function pushDictionary(ctx, params) {
+  const { slug, entries } = params;
+  const stage = await call(
+    ctx,
+    "POST",
+    `${base(ctx.appId)}/dictionary/stage`,
+    {
+      slug,
+      ...params.linkerVersion !== void 0 ? { linkerVersion: params.linkerVersion } : {}
+    }
+  );
+  const perPage = Math.min(
+    DICTIONARY_PAGE_ENTRIES,
+    stage.pageMaxEntries || DICTIONARY_PAGE_ENTRIES
+  );
+  let pages2 = 0;
+  let start2 = 0;
+  while (start2 < entries.length) {
+    let end = start2;
+    let bytes = 0;
+    while (end < entries.length && end - start2 < perPage) {
+      const size = JSON.stringify(entries[end]).length;
+      if (end > start2 && bytes + size > DICTIONARY_PAGE_BYTES) {
+        break;
+      }
+      bytes += size;
+      end += 1;
+    }
+    await call(ctx, "POST", `${base(ctx.appId)}/dictionary/page`, {
+      slug,
+      stageId: stage.stageId,
+      page: pages2,
+      entries: entries.slice(start2, end)
+    });
+    pages2 += 1;
+    start2 = end;
+    params.onProgress?.(start2, entries.length);
+  }
+  return call(
+    ctx,
+    "POST",
+    `${base(ctx.appId)}/dictionary/commit`,
+    { slug, stageId: stage.stageId, pages: pages2 }
+  );
+}
+function dictionary(ctx, params) {
+  return call(
+    ctx,
+    "POST",
+    `${base(ctx.appId)}/dictionary`,
+    { slug: params.slug }
+  );
+}
+function link(ctx, params) {
+  return call(ctx, "POST", `${base(ctx.appId)}/link`, {
+    slug: params.slug,
+    text: params.text
+  });
+}
 
 // src/ops/dataSourceJobs.ts
 var DEFAULT_WAIT_TIMEOUT_MS2 = 60 * 60 * 1e3;
@@ -3643,6 +3727,39 @@ function describeProgress(job, start2) {
 // src/commands/_shared/dataSources.ts
 var DEFAULT_SOURCE = "default";
 var sourceOf = (a) => a.str("source") || DEFAULT_SOURCE;
+function parseKeyValuePairs(raw, flag) {
+  if (raw === void 0) {
+    return void 0;
+  }
+  const pairs2 = {};
+  for (const part of raw.split(",")) {
+    const trimmed = part.trim();
+    if (!trimmed) {
+      continue;
+    }
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) {
+      fatal(`--${flag} entries must be key=value (got "${trimmed}").`);
+    }
+    const key = trimmed.slice(0, eq).trim();
+    const value = trimmed.slice(eq + 1).trim();
+    pairs2[key] = value === "true" ? true : value === "false" ? false : value !== "" && !Number.isNaN(Number(value)) ? Number(value) : value;
+  }
+  if (Object.keys(pairs2).length === 0) {
+    fatal(`--${flag} needs at least one key=value pair.`);
+  }
+  return pairs2;
+}
+function documentSelectorOf(raw) {
+  if (raw.trimStart().startsWith("{")) {
+    try {
+      return JSON.parse(raw);
+    } catch (err) {
+      fatal(`--filter is not valid JSON: ${err.message}`);
+    }
+  }
+  return { metadata: parseKeyValuePairs(raw, "filter") };
+}
 var timeoutOf = (a) => {
   const seconds = a.str("timeout");
   return seconds ? { timeoutMs: Number(seconds) * 1e3 } : {};
@@ -4658,9 +4775,116 @@ Retrieval evals:
   with --candidate, compare, promote or drop.
 `;
 
-// src/commands/dataSourceJobs.ts
+// src/commands/dataSourceDictionary.ts
 import fs4 from "fs";
 import path4 from "path";
+var dataSourceDictionarySpecs = {
+  "datasources dictionary push": {
+    usage: "Usage: remy-admin datasources dictionary push [--source <slug>] [--linker-version <n>] <file.jsonl>",
+    positionals: [{ name: "file", required: true }],
+    flags: {
+      source: { type: "string" },
+      "linker-version": { type: "number", min: 1 }
+    }
+  },
+  "datasources dictionary status": {
+    usage: "Usage: remy-admin datasources dictionary status [--source <slug>]",
+    flags: {
+      source: { type: "string" }
+    }
+  },
+  "datasources link": {
+    usage: "Usage: remy-admin datasources link [--source <slug>] <text>",
+    positionals: [{ name: "text", required: true }],
+    flags: {
+      source: { type: "string" }
+    }
+  }
+};
+function readEntries(file) {
+  const abs = path4.isAbsolute(file) ? file : path4.join(WORKSPACE_DIR, file);
+  let content;
+  try {
+    content = fs4.readFileSync(abs, "utf8");
+  } catch (err) {
+    fatal(`Could not read "${file}": ${err.message}`);
+  }
+  const entries = [];
+  content.split("\n").forEach((line, i) => {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      return;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      fatal(`${file}:${i + 1} is not valid JSON.`);
+    }
+    if (typeof parsed?.id !== "string" || !Array.isArray(parsed?.names) || !parsed.names.every((name) => typeof name === "string")) {
+      fatal(`${file}:${i + 1} needs { "id": "...", "names": ["...", ...] }.`);
+    }
+    entries.push({ id: parsed.id, names: parsed.names });
+  });
+  if (entries.length === 0) {
+    fatal(`"${file}" has no entries.`);
+  }
+  return entries;
+}
+async function dictionaryPush(ctx, a) {
+  const entries = readEntries(a.req("file"));
+  const linkerVersion = a.num("linker-version");
+  out(
+    await pushDictionary(ctx, {
+      slug: sourceOf(a),
+      entries,
+      ...linkerVersion !== void 0 ? { linkerVersion } : {},
+      onProgress: (sent, total) => progress(`pushing ${sent.toLocaleString()}/${total.toLocaleString()}\u2026`)
+    })
+  );
+}
+async function dictionaryStatus(ctx, a) {
+  out(await dictionary(ctx, { slug: sourceOf(a) }));
+}
+async function link2(ctx, a) {
+  out(await link(ctx, { slug: sourceOf(a), text: a.req("text") }));
+}
+var dataSourceDictionaryHandlers = {
+  "datasources dictionary push": dictionaryPush,
+  "datasources dictionary status": dictionaryStatus,
+  "datasources link": link2
+};
+var dataSourceDictionaryHelp = `
+Dictionary:
+  remy-admin datasources dictionary push [--source <slug>] [--linker-version <n>] <file.jsonl>
+  remy-admin datasources dictionary status [--source <slug>]
+  remy-admin datasources link [--source <slug>] <text>
+
+  A dictionary is your own entity ids and the names each goes by, a
+  projection of your tables: one JSONL line per entry,
+  {"id": "P-101A", "names": ["P-101A", "Main Feed Pump"]}. Push it whole; it
+  replaces the source's dictionary. From then on every passage carries the
+  ids whose names its text mentions, beside the ones its document asserts,
+  so --entities on search and count, and \`datasources entities\`, find a tag
+  wherever it's written. Passages indexed before are re-tagged in the
+  background (a relink; \`dictionary status\` shows it), with nothing
+  re-embedded. An unchanged dictionary commits nothing.
+
+  Matching ignores case and a tag's separators (P-101A, P101A, p 101a), takes
+  whole words only (P-101AB is not P-101A), and prefers the longest name; a
+  name two ids claim tags both. A name needs three letters or digits (two in
+  Chinese, Japanese or Korean). The push reports ambiguous names, the most
+  claimed, and names that can't match their own text as written
+  (\`unmatchable\`). Up to 250,000 entries, 16 names each, a million names.
+
+  \`link\` shows what the current dictionary finds in any text: check one
+  there before relying on it. --linker-version moves a dictionary to a newer
+  matching rule; without it a push keeps the one its dictionary has.
+`;
+
+// src/commands/dataSourceJobs.ts
+import fs5 from "fs";
+import path5 from "path";
 var dataSourceJobsSpecs = {
   "datasources jobs start": {
     usage: "Usage: remy-admin datasources jobs start [--source <slug>] (--store <name> [--access <private|public>] [--prefix <p>] | --manifest <file.jsonl>) [--limit <n>] [--budget <dollars>] [--concurrency <n>] [--priority] [--approve] [--wait] [--timeout <sec>]",
@@ -4738,10 +4962,10 @@ async function jobsStart(ctx, a) {
   }
   let source;
   if (manifest) {
-    const abs = path4.isAbsolute(manifest) ? manifest : path4.join(WORKSPACE_DIR, manifest);
+    const abs = path5.isAbsolute(manifest) ? manifest : path5.join(WORKSPACE_DIR, manifest);
     let content;
     try {
-      content = fs4.readFileSync(abs);
+      content = fs5.readFileSync(abs);
     } catch (err) {
       fatal(`Could not read manifest "${manifest}": ${err.message}`);
     }
@@ -4867,12 +5091,13 @@ Bulk ingestion (jobs):
   A job loads a whole corpus at once. It reads either every object under a
   prefix of one of the app's file stores (\`files put\` fills one; an app can
   write one at runtime) or a manifest you upload: JSONL, one line per document,
-  {"url": "https://\u2026", "filename": "x.pdf", "externalId": "\u2026", "metadata": {\u2026}}.
-  filename, externalId and metadata are optional; the URL must be public.
+  {"url": "https://\u2026", "filename": "x.pdf", "externalId": "\u2026", "metadata": {\u2026},
+  "entities": ["\u2026"]}. Everything but the URL is optional; it must be public.
 
-  Nothing is spent until you say so. The platform counts the source, reads a
-  sample of about a hundred documents, and writes a plan: documents, chunks,
-  cost per stage (embedding, extraction, contextual) at today's rates, storage,
+  Nothing past the sample runs until you say so. The platform counts the
+  source, reads a sample of about a hundred documents, and writes a plan:
+  documents, chunks, cost per stage (embedding, extraction, contextual, and
+  the mapper's own model calls, priced from the sample's) at today's rates, storage,
   whether it fits where the source lives, and a duration. \`jobs status\` shows
   it; \`jobs approve\` starts the run. Two gates: the corpus has to fit the
   source's placement (a shared-pool source over the per-source cap answers
@@ -4982,6 +5207,7 @@ function quarantine(ctx, params) {
     "GET",
     `${base5(ctx.appId)}/jobs/${params.id}/quarantine${qs({
       ...params.kind ? { kind: params.kind } : {},
+      ...params.stage ? { stage: params.stage } : {},
       ...params.reason ? { reason: params.reason } : {},
       ...params.cursor ? { cursor: params.cursor } : {},
       ...params.limit !== void 0 ? { limit: params.limit } : {}
@@ -5050,10 +5276,11 @@ var dataSourceMappersSpecs = {
     }
   },
   "datasources jobs quarantine": {
-    usage: "Usage: remy-admin datasources jobs quarantine <id> [--kind skip|error] [--reason <text>] [--cursor <id>] [--limit <n>]",
+    usage: "Usage: remy-admin datasources jobs quarantine <id> [--kind skip|error] [--stage map|read] [--reason <text>] [--cursor <id>] [--limit <n>]",
     positionals: [{ name: "id", required: true }],
     flags: {
       kind: { type: "string" },
+      stage: { type: "string" },
       reason: { type: "string" },
       cursor: { type: "string" },
       limit: { type: "number", min: 1 }
@@ -5206,18 +5433,32 @@ async function quarantine2(ctx, a) {
   const id = a.req("id");
   const limit = a.num("limit");
   const kind = kindOf(a);
+  const stage = a.str("stage");
+  if (stage !== void 0 && stage !== "map" && stage !== "read") {
+    fatal(`--stage must be "map" or "read" (got "${stage}").`);
+  }
   const reason = a.str("reason");
   const cursor = a.str("cursor");
   const result = await quarantine(ctx, {
     id,
     ...kind ? { kind } : {},
+    ...stage ? { stage } : {},
     ...reason ? { reason } : {},
     ...cursor ? { cursor } : {},
     ...limit !== void 0 ? { limit } : {}
   });
+  const { skipped, errors, readErrors } = result.counts;
+  const notes = [
+    ...skipped + errors > 0 ? [
+      `Mapping: fix the mapper, push, \`datasources map deploy\`, then \`datasources jobs replay ${id}\` to run these through it again.`
+    ] : [],
+    ...readErrors > 0 ? [
+      `Reading: fix the reader and publish, then \`datasources reader retry --source ${result.dataSource.slug} --job ${id}\` reads these again.`
+    ] : []
+  ];
   out({
     ...result,
-    note: result.counts.skipped + result.counts.errors === 0 ? "Nothing quarantined: the mapper produced documents (or deletions) for every object." : `Fix the mapper, push, \`datasources map deploy\`, then \`datasources jobs replay ${id}\` to run these through it again.`
+    note: notes.length === 0 ? "Nothing quarantined: the mapper produced documents (or deletions) for every object, and the reader read every document." : notes.join(" ")
   });
 }
 async function replay2(ctx, a) {
@@ -5258,7 +5499,7 @@ Mapping raw objects into documents (mappers):
   remy-admin datasources map test [--source <slug>] (--store <name> [--prefix <p>] | --connector) [--keys k1,k2] [--limit <n>] [--dev] [--full]
   remy-admin datasources map deploy [--source <slug>] [--release <id>]
   remy-admin datasources remap [--source <slug>] [--budget <dollars>] [--limit <n>] [--wait] [--timeout <sec>]
-  remy-admin datasources jobs quarantine <id> [--kind skip|error] [--reason <text>] [--cursor <id>] [--limit <n>]
+  remy-admin datasources jobs quarantine <id> [--kind skip|error] [--stage map|read] [--reason <text>] [--cursor <id>] [--limit <n>]
   remy-admin datasources jobs replay <id> [--kind skip|error] [--wait] [--timeout <sec>]
 
   A source takes every object it is given as one document. When the file is
@@ -5299,6 +5540,228 @@ Mapping raw objects into documents (mappers):
   pauses with pauseReason 'skips' for a look at the quarantine.
 `;
 
+// src/ops/dataSourceReaders.ts
+function base6(appId) {
+  return `/_internal/v2/apps/${appId}/datasources`;
+}
+function readerTest(ctx, params) {
+  return call(
+    ctx,
+    "POST",
+    `${base6(ctx.appId)}/reader/test`,
+    {
+      slug: params.slug,
+      ...params.documents ? { documents: params.documents } : {},
+      ...params.limit !== void 0 ? { limit: params.limit } : {}
+    }
+  );
+}
+function readerStatus(ctx, params) {
+  return call(
+    ctx,
+    "POST",
+    `${base6(ctx.appId)}/reader/status`,
+    { slug: params.slug }
+  );
+}
+function readerRetry(ctx, params) {
+  return call(
+    ctx,
+    "POST",
+    `${base6(ctx.appId)}/reader/retry`,
+    {
+      slug: params.slug,
+      ...params.jobId ? { jobId: params.jobId } : {}
+    }
+  );
+}
+function reread(ctx, params) {
+  return call(
+    ctx,
+    "POST",
+    `${base6(ctx.appId)}/reread`,
+    {
+      slug: params.slug,
+      ...params.unread ? { unread: true } : {},
+      ...params.filter ? { filter: params.filter } : {},
+      ...params.budgetDollars !== void 0 ? { budgetDollars: params.budgetDollars } : {},
+      ...params.limit !== void 0 ? { limit: params.limit } : {}
+    }
+  );
+}
+
+// src/commands/dataSourceReaders.ts
+var dataSourceReadersSpecs = {
+  "datasources reader test": {
+    usage: "Usage: remy-admin datasources reader test --dev [--source <slug>] [--documents id1,id2,...] [--limit <n>]",
+    flags: {
+      source: { type: "string" },
+      dev: { type: "boolean" },
+      documents: { type: "string" },
+      limit: { type: "number", min: 1 }
+    }
+  },
+  "datasources reader status": {
+    usage: "Usage: remy-admin datasources reader status [--source <slug>]",
+    flags: {
+      source: { type: "string" }
+    }
+  },
+  "datasources reader retry": {
+    usage: "Usage: remy-admin datasources reader retry [--source <slug>] [--job <id>]",
+    flags: {
+      source: { type: "string" },
+      job: { type: "string" }
+    }
+  },
+  "datasources reread": {
+    usage: "Usage: remy-admin datasources reread [--source <slug>] [--unread] [--filter <k=v,...|json>] [--budget <dollars>] [--limit <n>] [--wait] [--timeout <sec>]",
+    flags: {
+      source: { type: "string" },
+      unread: { type: "boolean" },
+      filter: { type: "string" },
+      budget: { type: "number", min: 0.01 },
+      limit: { type: "number", min: 1 },
+      wait: { type: "boolean" },
+      timeout: { type: "string" }
+    }
+  }
+};
+async function readerTest2(ctx, a) {
+  if (!a.bool("dev")) {
+    fatal(
+      "reader test runs the dev session's reader only: pass --dev. The live reader reads through deliveries and `datasources reread`."
+    );
+  }
+  const slug = sourceOf(a);
+  const raw = a.str("documents");
+  const documents2 = raw?.split(",").map((id) => id.trim()).filter(Boolean);
+  if (raw !== void 0 && documents2?.length === 0) {
+    fatal("--documents needs at least one document id.");
+  }
+  const limit = a.num("limit");
+  const result = await readerTest(ctx, {
+    slug,
+    ...documents2 ? { documents: documents2 } : {},
+    ...limit !== void 0 ? { limit } : {}
+  });
+  out({
+    dataSource: slug,
+    ...result,
+    note: "Ran the LOCAL reader through the dev session, writing into the dev session's database. Query its tables to check what it wrote; publish to make it the live reader, then `datasources reread --unread` reads what it has not."
+  });
+  if (result.failed > 0) {
+    throw new CliError(
+      `The reader failed on ${result.failed} of ${result.documents.length} document(s).`,
+      EXIT.buildFailed
+    );
+  }
+}
+async function readerStatus2(ctx, a) {
+  const slug = sourceOf(a);
+  const result = await readerStatus(ctx, { slug });
+  const { reader, deliveries, documents: documents2 } = result;
+  out({
+    dataSource: slug,
+    ...result,
+    note: !reader ? `The live release declares no reader for "${slug}". Declare one in mindstudio.json's dataSources and publish.` : deliveries.parked > 0 ? `${deliveries.parked} delivery(ies) failed six times and parked. Fix the reader and publish, then \`datasources reader retry\`.` : documents2.unread > 0 ? `${documents2.unread.toLocaleString()} live document(s) not read yet. \`datasources reread --unread\` plans reading them.` : "Every live document has been read."
+  });
+}
+async function readerRetry2(ctx, a) {
+  const slug = sourceOf(a);
+  const jobId = a.str("job");
+  const result = await readerRetry(ctx, {
+    slug,
+    ...jobId ? { jobId } : {}
+  });
+  out({
+    dataSource: slug,
+    ...jobId ? { job: jobId } : {},
+    ...result,
+    note: result.retried === 0 ? jobId ? `Job ${jobId}'s reader failed on nothing.` : "Nothing parked." : `Queued ${result.retried.toLocaleString()} delivery(ies) again; \`datasources reader status\` shows them drain.`
+  });
+}
+async function reread2(ctx, a) {
+  const slug = sourceOf(a);
+  const raw = a.str("filter");
+  const budget = a.num("budget");
+  const limit = a.num("limit");
+  const { job } = await reread(ctx, {
+    slug,
+    ...a.bool("unread") ? { unread: true } : {},
+    ...raw !== void 0 ? { filter: documentSelectorOf(raw) } : {},
+    ...budget !== void 0 ? { budgetDollars: budget } : {},
+    ...limit !== void 0 ? { limit } : {}
+  });
+  if (!a.bool("wait")) {
+    out({
+      dataSource: slug,
+      job,
+      note: `Planning: the reread prices reading from the reader's history, or reads a first slice for real to measure it. \`datasources jobs status ${job.id}\` shows the plan; \`datasources jobs approve ${job.id}\` runs it.`
+    });
+    return;
+  }
+  await waitAndReport(ctx, a, job.id, "plan", {
+    dataSource: slug,
+    action: "reread"
+  });
+}
+var dataSourceReadersHandlers = {
+  "datasources reader test": readerTest2,
+  "datasources reader status": readerStatus2,
+  "datasources reader retry": readerRetry2,
+  "datasources reread": reread2
+};
+var dataSourceReadersHelp = `
+Reading documents into the app (readers):
+  remy-admin datasources reader test --dev [--source <slug>] [--documents id1,id2] [--limit <n>]
+  remy-admin datasources reader status [--source <slug>]
+  remy-admin datasources reader retry [--source <slug>] [--job <id>]
+  remy-admin datasources reread [--source <slug>] [--unread] [--filter <k=v|json>] [--budget <dollars>] [--limit <n>] [--wait] [--timeout <sec>]
+
+  A READER is app code the platform runs over every document a source
+  builds, writing what it finds into the app's own tables: the extraction an
+  app would otherwise run from a cron over allDocuments(), with the
+  platform's batching, retries, budgets and pauses. Declare it in
+  mindstudio.json:
+    "dataSources": [{ "slug": "archive", "reader": { "path": "dist/datasources/archive.reader.ts" } }]
+  The file exports defineReader(Archive, { read, removed, cleared? }) from
+  @mindstudio-ai/agent. read(document) gets the document (id, sourceId,
+  filename, metadata, entities) and document.chunks(), its passages as
+  indexed with each one's entities; removed(documentId) is called when a
+  document leaves the source; cleared(sourceId) once when the source is
+  deleted. Throwing fails that document, which is retried. A document can be
+  read more than once, so read() replaces the document's rows as a set,
+  keyed by its id, and removed() deletes them. Options on the declaration:
+  timeoutMs (per document, default 60000, max 300000) and concurrency
+  (frames in flight for the source, default 16, max 64).
+
+  The reader always runs against the LIVE release, its code and its
+  database: nothing reads until the app publishes one. From then on every
+  document whose build lands on the active version is read, every removed
+  document delivered as removed, whether it came through add(), a sync or a
+  job. A job over a reader source reads as its last stage: the job stays
+  running until its documents are read, \`jobs status\` says "reading N of M",
+  a document the reader fails on lands in the job's quarantine (stage read),
+  and a reader failing on far more documents than it did at first pauses the
+  job with pauseReason 'reader'.
+
+  The loop: \`reader test --dev\` runs the LOCAL reader through the dev
+  session over real documents, writing into the dev session's database, and
+  prints each outcome; publish, and \`releases wait\` reports each reader's
+  unread documents; \`reread --unread\` reads them. \`reread\` is a job that
+  plans first: it prices reading from what the live reader has done (after a
+  hundred documents), or reads a first slice for real and measures spend,
+  failures and the live database's growth, then waits for \`jobs approve\`.
+  Without --unread it reads every built document again (a changed reader).
+  \`reader status\` shows the reader, its deliveries (pending, in flight,
+  retrying, parked, recent errors), unread documents, the measured cost per
+  document and the live database's size. Deliveries outside jobs retry after
+  1, 5, 15, 60 and 240 minutes, then park; \`reader retry\` sends parked ones
+  again, and \`reader retry --job <id>\` the documents a job's reader failed
+  on.
+`;
+
 // src/commands/dataSources.ts
 var INGEST_FLAGS = {
   chunking: { type: "string" },
@@ -5329,11 +5792,12 @@ var CONFIG_FLAGS = {
 };
 var dataSourcesSpecs = {
   "datasources add": {
-    usage: "Usage: remy-admin datasources add [--source <slug>] [--metadata <k=v,...>] [--wait] [--timeout <sec>] <file...>",
+    usage: "Usage: remy-admin datasources add [--source <slug>] [--metadata <k=v,...>] [--entities <id,...>] [--wait] [--timeout <sec>] <file...>",
     positionals: [{ name: "file", required: true, variadic: true }],
     flags: {
       source: { type: "string" },
       metadata: { type: "string" },
+      entities: { type: "string" },
       wait: { type: "boolean" },
       timeout: { type: "string" }
     }
@@ -5362,7 +5826,7 @@ var dataSourcesSpecs = {
     }
   },
   "datasources search": {
-    usage: "Usage: remy-admin datasources search [--source <slug>] [--top-k <n>] [--mode <hybrid|semantic|lexical>] [--filter <k=v,...|json>] [--phrase <text>] [--contains <words>] [--max-per-document <n>] [--rerank <true|false>] [--hybrid <true|false>] [--highlight] [--candidate] <query>",
+    usage: "Usage: remy-admin datasources search [--source <slug>] [--top-k <n>] [--mode <hybrid|semantic|lexical>] [--filter <k=v,...|json>] [--entities <id,...>] [--phrase <text>] [--contains <words>] [--max-per-document <n>] [--rerank <true|false>] [--hybrid <true|false>] [--highlight] [--candidate] <query>",
     positionals: [{ name: "query", required: true }],
     flags: {
       source: { type: "string" },
@@ -5372,6 +5836,7 @@ var dataSourcesSpecs = {
       hybrid: { type: "string" },
       mode: { type: "string" },
       filter: { type: "string" },
+      entities: { type: "string" },
       phrase: { type: "string" },
       contains: { type: "string" },
       "max-per-document": { type: "number", min: 1 },
@@ -5398,12 +5863,25 @@ var dataSourcesSpecs = {
     }
   },
   "datasources count": {
-    usage: "Usage: remy-admin datasources count [--source <slug>] [--filter <k=v,...|json>] [--contains <words>] [--phrase <text>] [--candidate]",
+    usage: "Usage: remy-admin datasources count [--source <slug>] [--filter <k=v,...|json>] [--entities <id,...>] [--contains <words>] [--phrase <text>] [--candidate]",
+    flags: {
+      source: { type: "string" },
+      filter: { type: "string" },
+      entities: { type: "string" },
+      contains: { type: "string" },
+      phrase: { type: "string" },
+      candidate: { type: "boolean" }
+    }
+  },
+  "datasources entities": {
+    usage: "Usage: remy-admin datasources entities [--source <slug>] [--filter <k=v,...|json>] [--entities <id,...>] [--contains <words>] [--phrase <text>] [--limit <n>] [--candidate]",
     flags: {
       source: { type: "string" },
       filter: { type: "string" },
+      entities: { type: "string" },
       contains: { type: "string" },
       phrase: { type: "string" },
+      limit: { type: "number", min: 1 },
       candidate: { type: "boolean" }
     }
   },
@@ -5449,22 +5927,24 @@ async function dataSourcesAdd(ctx, a) {
   const files = a.rest("file");
   const slug = sourceOf(a);
   const metadata = parseKeyValuePairs(a.str("metadata"), "metadata");
+  const entities2 = parseIdList(a.str("entities"));
   const results = [];
   for (const file of files) {
-    const abs = path5.isAbsolute(file) ? file : path5.join(WORKSPACE_DIR, file);
+    const abs = path6.isAbsolute(file) ? file : path6.join(WORKSPACE_DIR, file);
     let bytes;
     try {
-      bytes = fs5.readFileSync(abs);
+      bytes = fs6.readFileSync(abs);
     } catch (err) {
       fatal(`Could not read file "${file}": ${err.message}`);
     }
-    const filename = path5.basename(file);
+    const filename = path6.basename(file);
     results.push(
       await addDocument(ctx, {
         slug,
         filename,
         content: bytes,
         ...metadata ? { metadata } : {},
+        ...entities2 ? { entities: entities2 } : {},
         onProgress: progress
       })
     );
@@ -5535,6 +6015,7 @@ async function dataSourcesStatus(ctx, a) {
     activeVersion: source.activeVersion,
     candidate: source.candidate,
     job: source.job,
+    relink: source.relink,
     failures: (failures?.documents ?? []).map(summarize),
     moreFailures: !!failures?.nextCursor
   });
@@ -5550,16 +6031,7 @@ async function dataSourcesRm(ctx, a) {
     out({ deleted: documentId });
     return;
   }
-  let filter;
-  if (rawFilter.trimStart().startsWith("{")) {
-    try {
-      filter = JSON.parse(rawFilter);
-    } catch (err) {
-      fatal(`--filter is not valid JSON: ${err.message}`);
-    }
-  } else {
-    filter = { metadata: parseKeyValuePairs(rawFilter, "filter") };
-  }
+  const filter = documentSelectorOf(rawFilter);
   const slug = sourceOf(a);
   const result = await rmWhereAll(ctx, {
     slug,
@@ -5614,6 +6086,24 @@ async function dataSourcesCount(ctx, a) {
     })
   );
 }
+async function dataSourcesEntities(ctx, a) {
+  const filter = filterFromFlags(a);
+  const limit = a.num("limit");
+  out(
+    await entities(ctx, {
+      slug: sourceOf(a),
+      ...filter ? { filter } : {},
+      ...limit !== void 0 ? { limit } : {},
+      ...a.bool("candidate") ? { candidate: true } : {}
+    })
+  );
+}
+function parseIdList(raw) {
+  if (raw === void 0) {
+    return void 0;
+  }
+  return raw.split(",").map((id) => id.trim()).filter((id) => id.length > 0);
+}
 function filterFromFlags(a) {
   let filter = {};
   const raw = a.str("filter");
@@ -5631,6 +6121,10 @@ function filterFromFlags(a) {
       }
     }
   }
+  const entities2 = parseIdList(a.str("entities"));
+  if (entities2?.length) {
+    filter.entities = entities2;
+  }
   const phrase = a.str("phrase");
   if (phrase) {
     filter.phrase = phrase;
@@ -5641,29 +6135,6 @@ function filterFromFlags(a) {
   }
   return Object.keys(filter).length ? filter : void 0;
 }
-function parseKeyValuePairs(raw, flag) {
-  if (raw === void 0) {
-    return void 0;
-  }
-  const pairs2 = {};
-  for (const part of raw.split(",")) {
-    const trimmed = part.trim();
-    if (!trimmed) {
-      continue;
-    }
-    const eq = trimmed.indexOf("=");
-    if (eq <= 0) {
-      fatal(`--${flag} entries must be key=value (got "${trimmed}").`);
-    }
-    const key = trimmed.slice(0, eq).trim();
-    const value = trimmed.slice(eq + 1).trim();
-    pairs2[key] = value === "true" ? true : value === "false" ? false : value !== "" && !Number.isNaN(Number(value)) ? Number(value) : value;
-  }
-  if (Object.keys(pairs2).length === 0) {
-    fatal(`--${flag} needs at least one key=value pair.`);
-  }
-  return pairs2;
-}
 function triState2(a, flag, key) {
   const raw = a.str(flag);
   if (raw === void 0) {
@@ -5890,6 +6361,7 @@ var dataSourcesHandlers = {
   "datasources create": dataSourcesCreate,
   "datasources config": dataSourcesConfig,
   "datasources count": dataSourcesCount,
+  "datasources entities": dataSourcesEntities,
   "datasources move": dataSourcesMove,
   "datasources revectorize": dataSourcesRevectorize,
   "datasources promote": dataSourcesPromote,
@@ -5929,12 +6401,13 @@ Subcommands:
   delete       Delete a whole data source \u2014 documents, vectors and versions
 
 Usage:
-  remy-admin datasources add [--source <slug>] [--metadata <k=v,...>] [--wait] [--timeout <sec>] <file...>
+  remy-admin datasources add [--source <slug>] [--metadata <k=v,...>] [--entities <id,...>] [--wait] [--timeout <sec>] <file...>
   remy-admin datasources list
   remy-admin datasources status [--source <slug>] [--status error] [--all]
   remy-admin datasources rm [--source <slug>] (--document <id> | --filter <k=v,...|json>)
   remy-admin datasources search [--source <slug>] [search options] <query>
-  remy-admin datasources count [--source <slug>] [--filter <k=v,...|json>] [--contains <words>] [--phrase <text>] [--candidate]
+  remy-admin datasources count [--source <slug>] [--filter <k=v,...|json>] [--entities <id,...>] [--contains <words>] [--phrase <text>] [--candidate]
+  remy-admin datasources entities [--source <slug>] [--filter <k=v,...|json>] [--entities <id,...>] [--limit <n>] [--candidate]
   remy-admin datasources create --source <slug> [--name <name>] [--placement <resource-id|shared>] [rebuild settings...]
   remy-admin datasources config [--source <slug>] [--placement <resource-id|shared>] [settings...]
   remy-admin datasources move [--source <slug>] --to <resource-id|shared> [--chains <n>] [--restart] [--wait] [--timeout <sec>]
@@ -5955,6 +6428,15 @@ Count:
   count (none exists), and not the set search returns. The SDK's
   \`Source.count(filter)\` is the same call for an app.
 
+Entities:
+  A document can assert what it is about as your own ids (\`add --entities\`,
+  a mapper's \`entities\`, a manifest line's \`entities\`), and every passage
+  carries them. \`--entities a,b\` on search and count narrows to passages
+  about any of them. \`entities\` lists which entities the matching passages
+  are about, most first, with how many passages carry each (approximate, and
+  passages, not documents): filter on one entity to see what appears beside
+  it. The SDK's \`Source.entities({ filter, limit })\` is the same call.
+
 Search options:
   --top-k <n>              Results to return (default 5, max 50)
   --mode <m>               hybrid (default) | semantic | lexical. Lexical is
@@ -5963,11 +6445,12 @@ Search options:
   --filter <k=v,...>       Match document metadata set at add time. Values
                            coerce: true/false and numbers become typed.
                            Pass a JSON object for the full grammar:
-                           metadata, filename, documentIds, pages, contains,
-                           phrase \u2014 e.g. --filter '{"pages":{"max":3}}'.
+                           metadata, filename, documentIds, entities, pages,
+                           contains, phrase \u2014 e.g. --filter '{"pages":{"max":3}}'.
                            Metadata takes numeric ranges via {gte,lte}: store
                            dates as integers (YYYYMMDD or epoch seconds), then
                            --filter '{"metadata":{"date":{"gte":20250101}}}'
+  --entities <id,...>      Chunk must be about any of these entities
   --phrase <text>          Chunk must contain this exact word sequence
   --contains <words>       Chunk must contain ALL these words, any order
   --max-per-document <n>   Cap hits per document; backfills from others
@@ -6056,6 +6539,8 @@ Notes:
   Re-adding an unchanged file is free: no upload, no re-embedding. Re-adding
     with a different --metadata updates the tags in place, also free.
   --metadata tags documents for search-time filtering (scalars, \u226416 keys).
+  --entities names what a document is about, as your own ids (\u2264256, no spaces
+    or commas); an empty --entities clears them. Also free on a re-add.
   rm --filter removes every matching document in pages of a thousand: k=v
     pairs match metadata; a JSON object takes the full selector \u2014 metadata,
     filename, documentIds, externalIdPrefix (the key a job or connector
@@ -6095,7 +6580,7 @@ Examples:
   remy-admin datasources revectorize --source archive-sample --max-chars 900 --wait
   remy-admin datasources eval run --set <setId> --candidate --label small-chunks --wait
   remy-admin datasources eval compare <runA> <runB>
-${dataSourceJobsHelp}${dataSourceConnectorsHelp}${dataSourceMappersHelp}${dataSourceEvalsHelp}`;
+${dataSourceJobsHelp}${dataSourceConnectorsHelp}${dataSourceMappersHelp}${dataSourceReadersHelp}${dataSourceEvalsHelp}${dataSourceDictionaryHelp}`;
 
 // src/ops/voice.ts
 function normalizeE164(input) {
@@ -7932,21 +8417,21 @@ Examples:
 // src/ops/infra.ts
 var DEFAULT_WAIT_TIMEOUT_MS4 = 10 * 60 * 1e3;
 var POLL_MS5 = 3e3;
-function base6(appId) {
+function base7(appId) {
   return `/_internal/v2/apps/${appId}/infra`;
 }
 function list14(ctx, params) {
   return call(
     ctx,
     "GET",
-    `${base6(ctx.appId)}${params?.includeDestroyed ? "?includeDestroyed=true" : ""}`
+    `${base7(ctx.appId)}${params?.includeDestroyed ? "?includeDestroyed=true" : ""}`
   );
 }
 function get12(ctx, params) {
   return call(
     ctx,
     "GET",
-    `${base6(ctx.appId)}/${encodeURIComponent(params.id)}`
+    `${base7(ctx.appId)}/${encodeURIComponent(params.id)}`
   );
 }
 function logs(ctx, params) {
@@ -7961,11 +8446,11 @@ function logs(ctx, params) {
   return call(
     ctx,
     "GET",
-    `${base6(ctx.appId)}/${encodeURIComponent(params.id)}/logs${search2 ? `?${search2}` : ""}`
+    `${base7(ctx.appId)}/${encodeURIComponent(params.id)}/logs${search2 ? `?${search2}` : ""}`
   );
 }
 function provision(ctx, params) {
-  return call(ctx, "POST", base6(ctx.appId), {
+  return call(ctx, "POST", base7(ctx.appId), {
     offeringId: params.offeringId,
     ...params.name ? { name: params.name } : {}
   });
@@ -7974,28 +8459,28 @@ function hibernate(ctx, params) {
   return call(
     ctx,
     "POST",
-    `${base6(ctx.appId)}/${encodeURIComponent(params.id)}/hibernate`
+    `${base7(ctx.appId)}/${encodeURIComponent(params.id)}/hibernate`
   );
 }
 function resume2(ctx, params) {
   return call(
     ctx,
     "POST",
-    `${base6(ctx.appId)}/${encodeURIComponent(params.id)}/resume`
+    `${base7(ctx.appId)}/${encodeURIComponent(params.id)}/resume`
   );
 }
 function destroy(ctx, params) {
   return call(
     ctx,
     "POST",
-    `${base6(ctx.appId)}/${encodeURIComponent(params.id)}/destroy`
+    `${base7(ctx.appId)}/${encodeURIComponent(params.id)}/destroy`
   );
 }
 function resize(ctx, params) {
   return call(
     ctx,
     "POST",
-    `${base6(ctx.appId)}/${encodeURIComponent(params.id)}/resize`,
+    `${base7(ctx.appId)}/${encodeURIComponent(params.id)}/resize`,
     { offeringId: params.offeringId }
   );
 }
@@ -8003,7 +8488,7 @@ function rename(ctx, params) {
   return call(
     ctx,
     "POST",
-    `${base6(ctx.appId)}/${encodeURIComponent(params.id)}/rename`,
+    `${base7(ctx.appId)}/${encodeURIComponent(params.id)}/rename`,
     { name: params.name }
   );
 }
@@ -8572,7 +9057,9 @@ var SPECS = {
   ...dataSourceJobsSpecs,
   ...dataSourceConnectorsSpecs,
   ...dataSourceEvalsSpecs,
+  ...dataSourceDictionarySpecs,
   ...dataSourceMappersSpecs,
+  ...dataSourceReadersSpecs,
   ...voiceSpecs,
   ...agentSpecs,
   ...tasksSpecs,
@@ -8603,7 +9090,9 @@ var HANDLERS = {
   ...dataSourceJobsHandlers,
   ...dataSourceConnectorsHandlers,
   ...dataSourceEvalsHandlers,
+  ...dataSourceDictionaryHandlers,
   ...dataSourceMappersHandlers,
+  ...dataSourceReadersHandlers,
   ...voiceHandlers,
   ...agentHandlers,
   ...tasksHandlers,
@@ -8644,8 +9133,8 @@ var GROUP_HELP = {
 };
 
 // src/ctx.ts
-import fs6 from "fs";
-import path6 from "path";
+import fs7 from "fs";
+import path7 from "path";
 
 // src/parseJsonConfig.ts
 import JSON5 from "json5";
@@ -8674,10 +9163,10 @@ function parseJsonConfig(raw) {
 // src/ctx.ts
 var DEFAULT_BASE_URL = "https://api.mindstudio.ai";
 function loadWorkspaceAppId(workspaceDir = WORKSPACE_DIR) {
-  const manifestPath = path6.join(workspaceDir, "mindstudio.json");
+  const manifestPath = path7.join(workspaceDir, "mindstudio.json");
   let raw;
   try {
-    raw = fs6.readFileSync(manifestPath, "utf-8");
+    raw = fs7.readFileSync(manifestPath, "utf-8");
   } catch (err) {
     if (err.code === "ENOENT") {
       throw new Error(`mindstudio.json not found at ${manifestPath}`);