altalandi 0.6.1 → 0.6.2

package/README.md

@@ -107,8 +107,8 @@ altalandi --report --file draft.txt    # also write a Markdown report to ./altal
 | `--register` | `neutral` | `formal` \| `neutral` \| `warm` |
 | `--json` | off | print the full API response |
 | `--diff` | off | print the text before and after, then each change with its reason, on `stderr` (coloured in a terminal; `NO_COLOR` turns colour off) |
-| `--review` | off | print one Markdown block on `stdout`, made to be shown as it is: the verdict, the text before and after, each change with its reason, what the call cost and the balance and free units left. Exits on the outcome: `0` rewritten and verified or no change needed, `3` refused or unverified, `4` out of credit |
-| `--no-store` | off | send `contribute: false`: this text is never kept. Without it, free use (calls covered by the free daily units) is kept with personal data scrubbed, to improve the service; paid use is kept only with consent ([privacy](https://altalandi.is/personuvernd#textabanki)) |
+| `--review` | off | print one Markdown block on `stdout`, made to be shown as it is: the verdict, the text before and after, each change with its reason, what the call cost and the balance and free characters left. Exits on the outcome: `0` rewritten and verified or no change needed, `3` refused or unverified, `4` out of credit |
+| `--no-store` | off | send `contribute: false`: this text is never kept. Without it, free use (calls covered by the free daily characters) is kept with personal data scrubbed, to improve the service; paid use is kept only with consent ([privacy](https://altalandi.is/personuvernd#textabanki)) |
 | `--out <file>` | | write the refined text to `<file>` (UTF-8); with `--review` the block names it when the text is shortened |
 | `--report` | off | also write `./altalandi-reports/altalandi-<time>-<id>.md`: input, output, a table of every change (before, after, reason, layer), warnings and the verdict |
 | `--report-dir <dir>` | | write the report to `<dir>` instead (implies `--report`) |
@@ -127,8 +127,11 @@ altalandi https://example.com/pricing --out pricing-is.md   # one page → Markd
 altalandi https://example.com/docs/ --site --max-pages 50    # a site → ./example.com-is/
 ```
 
-Each passage (a paragraph, list item, table cell, heading or string) is its own
-call. Everything outside the passages is written back byte for byte:
+Each passage (a paragraph, list item, table cell, heading or string) is refined
+and checked on its own. Short passages (up to 1,500 characters) are sent
+together through `/v1/refine/batch`, up to 40 a request and 6,000 characters;
+longer ones go one call each to `/v1/refine`. Everything outside the passages is
+written back byte for byte:
 
 | format | refined | never touched |
 |--------|---------|---------------|
@@ -154,13 +157,19 @@ the same origin and under the URL's folder.
 from the public tariff:
 
 ```text
-5 files, 24 passages, about 851 characters (23 calls: repeated passages are sent once).
+5 files, 24 passages, about 851 characters (23 to send: repeated passages are sent once).
+1 request: 23 short passages together in 1 batch.
 1 more file has nothing to refine and is copied unchanged.
-Billing: about 920 units (at least 40 a call), about 74 kr if paid from credit. The free allowance is 2,000 units a day.
+Kostnaður: um 3.016 stafir (um 1 A4-síða), um 30 kr. ef greitt er af inneign.
+Hvert kall telst minnst 250 stafir; margir stuttir textar í einu kalli minnst 130 stafir hver. Hver aðgangur fær ókeypis dagskammt af stöfum (`GET /v1/pricing`).
 ```
 
-Every call costs at least the per-call minimum, so many short strings cost more
-than their word count. In a terminal it asks before sending; without one (CI,
+Billing is by character (stafir): every character sent, spaces and punctuation
+included. In a batch each string is billed at least 130 characters, and the
+250-character per-call minimum is paid once per request, not once per string:
+short strings cost about half what one call each would. The summary and the
+report show the characters actually billed. An older self-hosted engine without the batch endpoint gets one
+call per passage (the run says so once). In a terminal it asks before sending; without one (CI,
 agents) it sends nothing unless you pass `--yes`.
 
 | flag | default | meaning |
@@ -169,7 +178,7 @@ agents) it sends nothing unless you pass `--yes`.
 | `--dry-run` | off | list every passage and the estimate; send nothing, write nothing |
 | `--yes`, `-y` | off | send without asking |
 | `--max-chars <n>` | | files are sent in order until the next would go over n characters; the rest are neither sent nor written |
-| `--concurrency <n>` | `2` | calls at once, 1–4 |
+| `--concurrency <n>` | `2` | requests at once, 1–4 |
 | `--site` / `--max-pages <n>` | off / `20` | read a site from the URL, up to n pages |
 | `--no-store` | off | keep none of the passages (free use is otherwise kept, scrubbed of personal data) |
 | `--json` | off | a machine-readable summary of every file and passage on stdout |
@@ -255,6 +264,6 @@ the explicit verification opt-out and exits 0 after a successful API response.
 
 MIT licensed. Calls are paid from the account's prepaid credit (a 500 kr trial,
 then credit bought in the portal); a call the credit cannot cover exits with the
-server's `402 insufficient_balance` message. The request's text and glossary fields are charged at the effective billing-tier
-weight. Each whitespace-delimited token is at least one unit; an unbroken token
-uses one unit per 20 characters, rounded up.
+server's `402 insufficient_balance` message. The request's text and glossary fields are charged by the character
+(every Unicode character, spaces, punctuation and line breaks included) at the
+effective billing-tier weight, with a minimum per call.

package/auth.mjs

@@ -211,10 +211,8 @@ export async function runWhoami(flags = {}, io = {}) {
   const me = await res.json();
   if (flags.json) out(JSON.stringify({ ...me, keySource: source }, null, 2));
   else {
-    const { formatInt, formatIsk } = await import("./report.mjs");
-    const free = me.freeUnitsLeftToday != null && me.freeDailyUnits != null
-      ? `ókeypis eftir í dag ${formatInt(me.freeUnitsLeftToday)} af ${formatInt(me.freeDailyUnits)} einingum`
-      : me.freeDailyUnits ? `ókeypis ${formatInt(me.freeDailyUnits)} einingar á dag` : "";
+    const { formatIsk, freeCharsText } = await import("./report.mjs");
+    const free = freeCharsText(null, me);
     out([me.username ?? "(lykill án aðgangs)",
       `inneign ${me.balanceIsk != null ? formatIsk(me.balanceIsk) : "—"}`,
       free, `lykill ${me.keyId} (${source})`].filter(Boolean).join(" · "));

package/batch.mjs

@@ -4,12 +4,13 @@
 // The order of things is the safety story:
 //   1. plan      read every document and cut it into passages (segment.mjs,
 //                web.mjs); nothing is sent yet
-//   2. estimate  files, passages, characters and billing units, printed before
-//                anything is sent
+//   2. estimate  files, passages and the characters billed, with the price,
+//                printed before anything is sent
 //   3. consent   a y/N question in a terminal, or --yes; with neither, nothing
 //                is sent (--dry-run stops here on purpose)
-//   4. refine    one call per passage, 2 at a time by default; a 429 waits for
-//                Retry-After, a 402 stops the run cleanly
+//   4. refine    short passages go together in batch requests (/v1/refine/batch),
+//                longer ones one call each; 2 requests at a time by default; a
+//                429 waits for Retry-After, a 402 stops the run cleanly
 //   5. write     each file once all its passages are back; a passage whose
 //                meaning check did not pass keeps its original text; nothing is
 //                ever written inside the input
@@ -22,8 +23,8 @@ import { existsSync, statSync } from "node:fs";
 import { mkdir, readdir, readFile, realpath, writeFile } from "node:fs/promises";
 import path from "node:path";
 
-import { refine } from "./client.mjs";
-import { writeBatchReport } from "./report.mjs";
+import { refine, refineBatch } from "./client.mjs";
+import { CHARS_PER_WORD, charsEquivalent, formatChars, formatIsk, writeBatchReport } from "./report.mjs";
 import { assemble, FORMATS, isConfigJson, repairCodeSpans, segment, segmentMarkdown, splitForApi } from "./segment.mjs";
 import { pagePath, readPage, readSite, safeSegment, userAgent } from "./web.mjs";
 
@@ -39,6 +40,18 @@ const MAX_RETRY_WAIT_MS = 5 * 60_000; // a longer Retry-After means "come back l
 const MAX_RATE_LIMIT_RETRIES = 8;
 const MAX_TRANSIENT_RETRIES = 2;
 const ERRORS_IN_A_ROW_TO_STOP = 3;
+// Short passages go to /v1/refine/batch: each is billed at least 130 characters
+// there instead of the 250-character call minimum, which is paid once per
+// request. A request
+// stays small enough to come back well inside the web proxy's ~300 s timeout
+// (the server refines 4 at a time: ~40 short items take a minute or two).
+export const BATCH_PASSAGE_MAX_CHARS = 1500;
+export const BATCH_MAX_ITEMS = 40;
+export const BATCH_MAX_CHARS = 6000;
+// When /v1/pricing says neither (minimumBillableChars / batchItemMinimumChars)
+// nor the word units of an older engine.
+const MIN_BILLABLE_CHARS = 250;
+const BATCH_ITEM_MIN_CHARS = 130;
 const DOMAINS = ["general", "marketing", "data-analysis", "childrens-fiction"];
 const REGISTERS = ["formal", "neutral", "warm"];
 
@@ -60,10 +73,9 @@ const preview = (s, n = 72) => {
   return one.length > n ? `${one.slice(0, n - 1)}…` : one;
 };
 
-/** Every whitespace token is at least one billing unit; a long unbroken token
- *  is one unit per 20 characters (the server's rule, docs/api/README.md). */
-const billingTokens = (text) => text.split(/\s+/).filter(Boolean)
-  .reduce((n, t) => n + Math.max(1, Math.ceil(t.length / 20)), 0);
+/** Billable characters: every Unicode code point of the trimmed text, spaces,
+ *  punctuation and line breaks included (the server's rule). */
+export const billableChars = (text) => [...String(text).trim()].length;
 
 /** The real path of p, or of its deepest existing ancestor plus the rest, so a
  *  symlinked --out is compared where it really points. */
@@ -222,6 +234,31 @@ function buildCalls(files, maxChars) {
   return [...calls.values()];
 }
 
+/** The requests of a run: short calls together in batches of at most
+ *  BATCH_MAX_ITEMS items and BATCH_MAX_CHARS characters, longer ones alone. */
+export function groupCalls(calls) {
+  const jobs = [];
+  let open = null;
+  for (const call of calls) {
+    if (call.text.length > BATCH_PASSAGE_MAX_CHARS) { jobs.push({ batch: false, calls: [call] }); continue; }
+    if (open && (open.calls.length >= BATCH_MAX_ITEMS || open.chars + call.text.length > BATCH_MAX_CHARS)) open = null;
+    if (!open) { open = { batch: true, calls: [], chars: 0 }; jobs.push(open); }
+    open.calls.push(call);
+    open.chars += call.text.length;
+  }
+  return jobs;
+}
+
+/** Characters a request is billed: the call minimum for one text; for a batch,
+ *  each item at least the item minimum, the call minimum once for the request. */
+function jobChars(job, pricing) {
+  if (!job.batch) return Math.max(pricing.minChars, billableChars(job.calls[0].text));
+  const items = job.calls.reduce((n, c) => n + Math.max(pricing.itemMinChars, billableChars(c.text)), 0);
+  return Math.max(pricing.minChars, items);
+}
+
+const fin = (v) => (typeof v === "number" && Number.isFinite(v) ? v : null);
+
 async function fetchPricing(baseUrl, fetchImpl) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), 5000);
@@ -230,12 +267,20 @@ async function fetchPricing(baseUrl, fetchImpl) {
     if (!res.ok) return null;
     const p = JSON.parse(await res.text());
     const lane = p?.tiers?.standard?.fast;
-    if (!Number.isFinite(p?.minimumBillableUnits) || !lane) return null;
+    if (!lane || typeof lane !== "object") return null;
+    // Characters (billingUnit "character"); an engine from before the switch
+    // gives word units, converted with charsPerWord.
+    const cpw = fin(p.charsPerWord) > 0 ? p.charsPerWord : CHARS_PER_WORD;
+    const chars = (c, u) => fin(p[c]) ?? (fin(p[u]) != null ? Math.round(p[u] * cpw) : null);
+    // The tier's price already carries its weight, as iskPer1000Units did.
+    const per100 = fin(lane.iskPer100Chars) ?? (fin(lane.iskPer1000Units) != null ? lane.iskPer1000Units / 10 / cpw : null);
     return {
-      minUnits: p.minimumBillableUnits,
+      minChars: chars("minimumBillableChars", "minimumBillableUnits") ?? MIN_BILLABLE_CHARS,
+      itemMinChars: chars("batchItemMinimumChars", "batchItemMinimumUnits") ?? BATCH_ITEM_MIN_CHARS,
       multiplier: Number(lane.multiplier) || 1,
-      iskPer1000: Number(lane.iskPer1000Units),
-      freeDaily: Number(p.accountFreeDailyUnits) || 0,
+      iskPerChar: per100 != null ? per100 / 100 : null,
+      freeDaily: chars("accountFreeDailyChars", "accountFreeDailyUnits") ?? 0,
+      charsPerWord: cpw,
     };
   } catch {
     return null;
@@ -244,14 +289,22 @@ async function fetchPricing(baseUrl, fetchImpl) {
   }
 }
 
-function estimateLines(plan, calls, pricing, opts) {
+function estimateLines(plan, calls, jobs, pricing, opts) {
   const refining = plan.files.filter((f) => f.status === "refine");
   const passages = refining.reduce((n, f) => n + f.units.length, 0);
   const chars = calls.reduce((n, c) => n + c.text.length, 0);
   const lines = [
     `${plural(refining.length, "file", "files")}, ${plural(passages, "passage", "passages")}, about ${fmt(chars)} characters`
-      + `${calls.length !== passages ? ` (${plural(calls.length, "call", "calls")}: repeated passages are sent once)` : ""}.`,
+      + `${calls.length !== passages ? ` (${fmt(calls.length)} to send: repeated passages are sent once)` : ""}.`,
   ];
+  const batches = jobs.filter((j) => j.batch);
+  if (calls.length) {
+    const together = batches.reduce((n, j) => n + j.calls.length, 0);
+    const alone = jobs.length - batches.length;
+    lines.push(`${plural(jobs.length, "request", "requests")}: `
+      + [together && `${plural(together, "short passage", "short passages")} together in ${plural(batches.length, "batch", "batches")}`,
+        alone && `${plural(alone, "longer passage", "longer passages")} one by one`].filter(Boolean).join(", ") + ".");
+  }
   const copied = plan.files.filter((f) => f.status === "copy").length;
   if (copied) lines.push(`${plural(copied, "more file has", "more files have")} nothing to refine and ${copied === 1 ? "is" : "are"} copied unchanged.`);
   const over = plan.files.filter((f) => f.status === "over-budget");
@@ -260,10 +313,16 @@ function estimateLines(plan, calls, pricing, opts) {
       + `(from ${over[0].path} on).`);
   }
   if (pricing && calls.length) {
-    const units = calls.reduce((n, c) => n + Math.max(pricing.minUnits, billingTokens(c.text)), 0) * pricing.multiplier;
-    const isk = Number.isFinite(pricing.iskPer1000) ? `, about ${fmt((units * pricing.iskPer1000) / 1000)} kr if paid from credit` : "";
-    lines.push(`Billing: about ${fmt(units)} units (at least ${fmt(pricing.minUnits)} a call)${isk}.`
-      + `${pricing.freeDaily ? ` The free allowance is ${fmt(pricing.freeDaily)} units a day.` : ""}`);
+    // In Icelandic, as on the site: characters, one equivalent and krónur;
+    // never the rate per 100 characters.
+    const raw = jobs.reduce((n, j) => n + jobChars(j, pricing), 0);
+    const billed = raw * pricing.multiplier;
+    const isk = pricing.iskPerChar != null ? raw * pricing.iskPerChar : null;
+    const price = isk != null ? `, um ${formatIsk(isk >= 10 ? Math.round(isk) : isk)} ef greitt er af inneign` : "";
+    lines.push(`Kostnaður: um ${formatChars(billed)} (${charsEquivalent(billed)})${price}.`);
+    const rule = `Hvert kall telst minnst ${formatChars(pricing.minChars)}`
+      + (batches.length ? `; margir stuttir textar í einu kalli minnst ${formatChars(pricing.itemMinChars)} hver.` : ".");
+    lines.push(rule + (pricing.freeDaily ? ` ${formatChars(pricing.freeDaily)} á dag eru ókeypis.` : ""));
   }
   return lines;
 }
@@ -369,6 +428,7 @@ export async function runBatch(opts, io = {}) {
     return EXIT_ERROR;
   }
   const calls = buildCalls(plan.files, opts.maxChars);
+  const jobs = groupCalls(calls);
   const baseUrl = (opts.baseUrl || "https://altalandi.is/api").replace(/\/+$/, "");
   const where = `${plan.label} → ${display(plan.output, cwd)}`;
   const refining = () => plan.files.filter((f) => f.status === "refine");
@@ -379,7 +439,7 @@ export async function runBatch(opts, io = {}) {
   }
   // The public tariff: no key, no text sent, nothing charged.
   const pricing = calls.length ? await fetchPricing(baseUrl, fetchImpl) : null;
-  const estimate = estimateLines(plan, calls, pricing, opts);
+  const estimate = estimateLines(plan, calls, jobs, pricing, opts);
 
   if (opts.dryRun) {
     if (opts.json) {
@@ -434,7 +494,18 @@ export async function runBatch(opts, io = {}) {
     await writeFile(target, data);
   };
 
-  const state = { stop: null, pausedUntil: 0, errorsInARow: 0 };
+  const state = { stop: null, pausedUntil: 0, errorsInARow: 0, noBatch: false, billed: null, billedChars: null, approx: false };
+  // What a response says it billed: characters, or the word units of an
+  // engine from before the switch (converted, and marked as approximate).
+  const bill = (data) => {
+    const b = data?.billing || {};
+    const units = fin(b.units) ?? fin(data?.units);
+    if (units != null) state.billed = (state.billed ?? 0) + units;
+    const chars = fin(b.characters) ?? fin(data?.characters);
+    if (chars == null && units == null) return;
+    if (chars == null) state.approx = true;
+    state.billedChars = (state.billedChars ?? 0) + (chars ?? units * (pricing?.charsPerWord ?? CHARS_PER_WORD));
+  };
   const stop = (reason, message) => { if (!state.stop) state.stop = { reason, message }; };
 
   for (const f of plan.files.filter((x) => x.status === "copy")) {
@@ -453,15 +524,19 @@ export async function runBatch(opts, io = {}) {
     for (let left = state.pausedUntil - now(); left > 0; left = state.pausedUntil - now()) await wait(left);
   };
 
-  const callOnce = async (call) => {
+  // One request with the run's retry rules: `send` is one /v1/refine or one
+  // /v1/refine/batch call. A batch endpoint the server does not have (404/405,
+  // an older self-hosted engine) answers { unsupported }.
+  const attempt = async (send, { batch = false } = {}) => {
     let rateLimited = 0;
     let transient = 0;
     for (;;) {
       await pause();
       if (state.stop) return { skipped: true };
       try {
-        return { data: await refine(call.text, requestOptions) };
+        return { data: await send() };
       } catch (e) {
+        if (batch && (e.status === 404 || e.status === 405)) return { unsupported: true };
         if (e.status === 429) {
           rateLimited++;
           const ms = Number.isFinite(e.retryAfterMs) ? e.retryAfterMs : Math.min(60_000, 2000 * 2 ** (rateLimited - 1));
@@ -515,32 +590,97 @@ export async function runBatch(opts, io = {}) {
     }
   };
 
-  const done = async (call) => {
-    if (call.result.skipped) return;
-    if (call.result.error) {
-      state.errorsInARow++;
-      if (state.errorsInARow >= ERRORS_IN_A_ROW_TO_STOP) stop("error", `${state.errorsInARow} calls in a row failed; the last: ${call.result.error}`);
-    } else {
-      state.errorsInARow = 0;
+  const countError = (error) => {
+    state.errorsInARow++;
+    if (state.errorsInARow >= ERRORS_IN_A_ROW_TO_STOP) stop("error", `${state.errorsInARow} calls in a row failed; the last: ${error}`);
+  };
+
+  const done = async (job) => {
+    if (job.calls.some((c) => c.result?.skipped)) return;
+    if (job.failed) countError(job.failed); // a whole request failed: one error, not one per passage
+    else {
+      for (const call of job.calls) {
+        if (call.result.error) countError(call.result.error);
+        else state.errorsInARow = 0;
+      }
     }
-    for (const unit of call.units) {
-      if (unit.status || !unit.calls.every((c) => c.result && !c.result.skipped)) continue;
-      settle(unit);
-      const file = unit.file;
-      if (file.status === "refine" && file.units.every((u) => u.status)) await finish(file);
+    for (const call of job.calls) {
+      for (const unit of call.units) {
+        if (unit.status || !unit.calls.every((c) => c.result && !c.result.skipped)) continue;
+        settle(unit);
+        const file = unit.file;
+        if (file.status === "refine" && file.units.every((u) => u.status)) await finish(file);
+      }
     }
   };
 
+  const single = async (call) => {
+    const r = await attempt(() => refine(call.text, requestOptions));
+    if (r.data) bill(r.data);
+    return r;
+  };
+
+  /** One batch request; every item is mapped back to its call by id. */
+  const sendBatch = async (job) => {
+    const items = job.calls.map((c, k) => ({ id: String(k), text: c.text }));
+    const r = await attempt(() => refineBatch(items, requestOptions), { batch: true });
+    if (!r.data) return r;
+    const data = r.data;
+    bill(data);
+    const byId = new Map(data.items.map((it) => [String(it.id), it]));
+    const artifacts = data.quality?.encodingArtifacts || [];
+    job.calls.forEach((call, k) => {
+      const item = byId.get(String(k));
+      if (!item) call.result = { error: "the batch response has no result for this passage" };
+      else if (item.error) call.result = { error: String(item.error) };
+      else {
+        // The batch's quality block covers every item; keep the mojibake guard per item.
+        const own = artifacts.filter((a) => a && String(item.output).includes(a));
+        call.result = { data: { ...item, id: data.id || undefined, quality: { encodingArtifacts: own } } };
+      }
+    });
+    return { done: true };
+  };
+
+  const alone = (job) => job.calls.map((call) => ({ batch: false, calls: [call] }));
   const hadWork = refining().length > 0;
-  const queue = [...calls];
+  const queue = [...jobs];
   const worker = async () => {
     while (queue.length && !state.stop) {
-      const call = queue.shift();
-      call.result = await callOnce(call);
-      await done(call);
+      const job = queue.shift();
+      if (job.batch && state.noBatch) { queue.unshift(...alone(job)); continue; }
+      if (!job.batch) {
+        job.calls[0].result = await single(job.calls[0]);
+      } else {
+        const r = await sendBatch(job);
+        if (r.unsupported) {
+          if (!state.noBatch) {
+            state.noBatch = true;
+            log("Note: this server has no batch endpoint (/v1/refine/batch), so every passage is sent on its own "
+              + `(each call is billed at least ${fmt(pricing?.minChars ?? MIN_BILLABLE_CHARS)} characters).`);
+          }
+          queue.unshift(...alone(job));
+          fill(); // one batch became many calls: use every worker for them
+          continue;
+        }
+        if (!r.done) {
+          for (const call of job.calls) call.result = r;
+          if (r.error) job.failed = r.error;
+        }
+      }
+      await done(job);
     }
   };
-  await Promise.all(Array.from({ length: Math.min(concurrency, Math.max(1, calls.length)) }, worker));
+  const running = [];
+  let active = 0;
+  function fill() {
+    while (active < concurrency && queue.length && !state.stop) {
+      active++;
+      running.push(worker().finally(() => { active--; }));
+    }
+  }
+  fill();
+  while (running.length) await Promise.all(running.splice(0));
 
   for (const f of plan.files) if (f.status === "refine") f.status = "unfinished";
 
@@ -576,6 +716,12 @@ export async function runBatch(opts, io = {}) {
       kept: count("kept"),
       failed: count("failed"),
       characters: calls.filter((c) => c.result && !c.result.skipped).reduce((n, c) => n + c.text.length, 0),
+      // What the server says it billed, summed over the responses (null: none
+      // said). billedCharacters is what is shown; units is the word equivalent.
+      billedCharacters: state.billedChars == null ? null
+        : state.approx ? Math.round(state.billedChars / 10) * 10 : Math.round(state.billedChars),
+      ...(state.approx ? { billedCharactersApprox: true } : {}),
+      units: state.billed,
     },
     ...(plan.skipped?.length ? { skippedPages: plan.skipped } : {}),
     files,
@@ -612,6 +758,9 @@ export async function runBatch(opts, io = {}) {
   log(`\n${state.stop ? "Partly done" : "Done"}: ${plural(t.written + t.unchanged + t.copied, "file", "files")} in ${display(plan.output, cwd)}`
     + `${t.copied ? ` (${fmt(t.copied)} copied unchanged)` : ""}.`
     + (hadWork ? ` Passages: ${fmt(t.changed)} changed, ${fmt(t.unchangedPassages)} needed no change, ${fmt(t.kept)} kept as they were, ${fmt(t.failed)} failed.` : ""));
+  if (t.billedCharacters != null) {
+    log(`Rukkað: ${t.billedCharactersApprox ? "um " : ""}${formatChars(t.billedCharacters)} (${charsEquivalent(t.billedCharacters)}).`);
+  }
   if (t.kept) log(`${plural(t.kept, "passage keeps", "passages keep")} the original text because a check did not pass; the report lists ${t.kept === 1 ? "it" : "them"}.`);
   if (t.overBudget) log(`${plural(t.overBudget, "file was", "files were")} left out for --max-chars.`);
   if (summary.report) log(`Report: ${display(summary.report, cwd)}`);

package/client.d.ts

@@ -87,6 +87,10 @@ export interface RefineResult {
   warnings: string[];
   /** true when a test key made the call: no model ran, nothing was charged, output = input. */
   test?: boolean | null;
+  /** Characters billed (= billing.characters); absent from engines before character billing. */
+  characters?: number;
+  /** /v1 only: what the call cost and what is left (characters, chargedIsk, balanceIsk, freeCharsLeftToday, …). */
+  billing?: Record<string, unknown> | null;
 }
 
 export type VerifiedRefineResult = RefineResult & { meaningPreserved: true };
@@ -113,6 +117,59 @@ export class MeaningVerificationError extends AltalandiError {
 /** Refine text and return the full hosted API response. */
 export function refine(text: string, options?: RefineOptions): Promise<RefineResult>;
 
+export interface BatchItem {
+  /** Your key for the string; defaults to its index, as a string. */
+  id?: string;
+  /** At most 2,000 characters. */
+  text: string;
+}
+
+export interface BatchOptions {
+  sourceLang?: SourceLang;
+  domain?: Domain;
+  register?: Register;
+  preserveMeaning?: boolean;
+  scoreNativeness?: boolean;
+  onlyImprove?: boolean;
+  glossary?: GlossaryTerm[];
+  autoTerminology?: boolean;
+  contribute?: boolean;
+  apiKey?: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+  fetch?: FetchLike;
+}
+
+export interface BatchItemResult {
+  id: string;
+  output: string;
+  sourceLang: "en" | "is";
+  diffs: RefineDiff[];
+  meaningCheck: "passed" | "changed" | "reverted" | "skipped" | "unavailable";
+  meaningPreserved: boolean | null;
+  warnings: string[];
+  /** true: refined in one model call with other strings, then checked on its own. */
+  packed: boolean;
+  /** Set when this string could not be refined: it came back unchanged and was not billed. */
+  error?: string | null;
+}
+
+export interface BatchResult {
+  id: string;
+  runUrl: string | null;
+  items: BatchItemResult[];
+  /** Characters billed for the whole batch (= billing.characters); absent from engines before character billing. */
+  characters?: number;
+  /** @deprecated The word equivalent of `characters` (= billing.units). */
+  units: number;
+  billing: Record<string, unknown> | null;
+  quality: RefineQuality;
+  warnings: string[];
+}
+
+/** Refine many short strings in one call (POST /v1/refine/batch). */
+export function refineBatch(items: BatchItem[], options?: BatchOptions): Promise<BatchResult>;
+
 /** Refine text and throw unless meaningPreserved is strict true. */
 export function refineVerified(text: string, options?: RefineOptions): Promise<VerifiedRefineResult>;
 

package/client.mjs

@@ -14,6 +14,18 @@ const REQUEST_FIELDS = [
   "returnDiffs",
   "contribute",
 ];
+// /v1/refine/batch takes fewer options: no writer/scoring tiers, polish or diffs switch.
+const BATCH_REQUEST_FIELDS = [
+  "sourceLang",
+  "domain",
+  "register",
+  "preserveMeaning",
+  "scoreNativeness",
+  "onlyImprove",
+  "glossary",
+  "autoTerminology",
+  "contribute",
+];
 
 export class AltalandiError extends Error {
   constructor(message, { code = "ALTALANDI_ERROR", status, retryAfterMs } = {}) {
@@ -80,16 +92,10 @@ function requestBody(text, options) {
   return body;
 }
 
-/**
- * Refine English or Icelandic text through the hosted Altalandi API.
- * Client settings (`apiKey`, `baseUrl`, `timeoutMs`, `fetch`) are never sent in
- * the JSON body. The full API result is returned without weakening its verdict.
- */
-export async function refine(text, options = {}) {
-  if (typeof text !== "string" || !text.trim()) {
-    throw new AltalandiError("Altalandi requires non-empty text.", { code: "INVALID_INPUT" });
-  }
-
+/** POST a JSON body to `${baseUrl}${route}` with the key, base URL, timeout and
+ *  error handling every call shares. Returns the payload when `validShape`
+ *  accepts it; throws an AltalandiError (with status and Retry-After) otherwise. */
+async function post(route, body, options, validShape) {
   const explicitKey = options.apiKey;
   const selectedKey = explicitKey === undefined ? env("ALTALANDI_API_KEY") : explicitKey;
   if (selectedKey !== undefined && typeof selectedKey !== "string") {
@@ -129,13 +135,13 @@ export async function refine(text, options = {}) {
   try {
     let response;
     try {
-      response = await fetchImpl(`${baseUrl}/v1/refine`, {
+      response = await fetchImpl(`${baseUrl}${route}`, {
         method: "POST",
         headers: {
           "content-type": "application/json",
           authorization: `Bearer ${apiKey}`,
         },
-        body: JSON.stringify(requestBody(text, options)),
+        body: JSON.stringify(body),
         signal: controller.signal,
       });
     } catch {
@@ -190,7 +196,7 @@ export async function refine(text, options = {}) {
       );
     }
 
-    if (!payload || typeof payload !== "object" || Array.isArray(payload) || typeof payload.output !== "string") {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload) || !validShape(payload)) {
       throw new AltalandiError("Altalandi returned an invalid response shape.", {
         code: "INVALID_RESPONSE",
         status: response.status,
@@ -203,6 +209,39 @@ export async function refine(text, options = {}) {
   }
 }
 
+/**
+ * Refine English or Icelandic text through the hosted Altalandi API.
+ * Client settings (`apiKey`, `baseUrl`, `timeoutMs`, `fetch`) are never sent in
+ * the JSON body. The full API result is returned without weakening its verdict.
+ */
+export async function refine(text, options = {}) {
+  if (typeof text !== "string" || !text.trim()) {
+    throw new AltalandiError("Altalandi requires non-empty text.", { code: "INVALID_INPUT" });
+  }
+  return post("/v1/refine", requestBody(text, options), options, (p) => typeof p.output === "string");
+}
+
+/**
+ * Refine many short strings in one call (POST /v1/refine/batch): at most 500
+ * items of at most 2,000 characters each, 20,000 characters together. Each item
+ * comes back with its own output and meaning verdict; an item with `error` came
+ * back unchanged and was not billed. Same key, limits and errors as refine().
+ */
+export async function refineBatch(items, options = {}) {
+  if (!Array.isArray(items) || !items.length
+    || !items.every((it) => it && typeof it.text === "string" && (it.id === undefined || typeof it.id === "string"))) {
+    throw new AltalandiError("Altalandi refineBatch requires a non-empty list of { id?, text } items.", {
+      code: "INVALID_INPUT",
+    });
+  }
+  const body = { items: items.map((it) => (it.id === undefined ? { text: it.text } : { id: it.id, text: it.text })) };
+  for (const field of BATCH_REQUEST_FIELDS) {
+    if (options[field] !== undefined) body[field] = options[field];
+  }
+  return post("/v1/refine/batch", body, options, (p) => Array.isArray(p.items)
+    && p.items.every((it) => it && typeof it === "object" && typeof it.output === "string"));
+}
+
 /** Assert that an existing result carries a completed, positive meaning check. */
 export function assertMeaningVerified(result) {
   if (result?.meaningPreserved !== true) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "altalandi",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Native-sounding Icelandic from your terminal or AI agent: one-time login, a Claude Code skill, and meaning verification.",
   "type": "module",
   "main": "./client.mjs",

package/report.mjs

@@ -154,6 +154,64 @@ export function formatIsk(n) {
 
 const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : null);
 
+// ── characters (stafir) ─────────────────────────────────────────────────────
+// Billing is in characters. Engines from before the switch send only word
+// units; those are shown as characters too (units × charsPerWord, rounded to
+// tens and marked "um"). The per-100-characters rate is never shown: amounts
+// in krónur and friendly equivalents (an A4 page) only.
+
+/** Characters per word, when an engine does not say (`charsPerWord`). */
+export const CHARS_PER_WORD = 6.5;
+/** A normal A4 page (display only). */
+export const CHARS_PER_A4_PAGE = 3200;
+
+const singular = (n) => { const k = Math.round(Math.abs(n)); return k % 10 === 1 && k % 100 !== 11; };
+
+/** 2690 → "2.690 stafir", 21 → "21 stafur". */
+export function formatChars(n) {
+  return `${formatInt(n)} ${singular(n) ? "stafur" : "stafir"}`;
+}
+
+/** One friendly equivalent: "um 7 A4-síður", "um 1 A4-síða", "innan við hálfa A4-síðu". */
+export function charsEquivalent(n) {
+  const pages = Math.round(Number(n) / CHARS_PER_A4_PAGE);
+  if (pages < 1) return "innan við hálfa A4-síðu";
+  return `um ${formatInt(pages)} ${singular(pages) ? "A4-síða" : "A4-síður"}`;
+}
+
+/** Word units of an older engine as characters, rounded to tens. */
+export function unitsToChars(units, charsPerWord = CHARS_PER_WORD) {
+  return Math.round((Number(units) * charsPerWord) / 10) * 10;
+}
+
+const perWord = (...from) => from.map((o) => num(o?.charsPerWord)).find((v) => v != null && v > 0) ?? CHARS_PER_WORD;
+
+/** The first source with a characters field wins; else the first with word
+ *  units, converted. → { n, approx } or null. */
+function charsOf(sources, charsKey, unitsKey, cpw) {
+  for (const s of sources) if (num(s?.[charsKey]) != null) return { n: s[charsKey], approx: false };
+  for (const s of sources) if (num(s?.[unitsKey]) != null) return { n: unitsToChars(s[unitsKey], cpw), approx: true };
+  return null;
+}
+
+/** Today's free allowance: "ókeypis eftir í dag 9.800 af 15.000 stöfum".
+ *  `billing` is a call's billing block, `after`/`before` the /v1/me answers
+ *  after and before it; any may be null. "" when nothing is known. */
+export function freeCharsText(billing, after = null, before = null) {
+  const cpw = perWord(billing, after, before);
+  const left = charsOf([billing, after], "freeCharsLeftToday", "freeUnitsLeftToday", cpw);
+  const daily = charsOf([after, before], "freeDailyChars", "freeDailyUnits", cpw);
+  // One "um", before the first converted number that is not 0.
+  const um = (c) => (c?.approx && c.n ? "um " : "");
+  if (left && daily) {
+    const [a, b] = um(left) ? ["um ", ""] : ["", um(daily)];
+    return `ókeypis eftir í dag ${a}${formatInt(left.n)} af ${b}${formatInt(daily.n)} ${singular(daily.n) ? "staf" : "stöfum"}`;
+  }
+  if (left) return `ókeypis eftir í dag ${um(left)}${formatChars(left.n)}`;
+  if (daily && daily.n > 0) return `ókeypis ${um(daily)}${formatChars(daily.n)} á dag`;
+  return "";
+}
+
 /**
  * What the call cost and what is left. `data.billing` (sent by newer engines)
  * is exact; otherwise the cost is the balance difference between /v1/me
@@ -167,24 +225,21 @@ export function costLines(data, before, after) {
   if (charged == null && num(before?.balanceIsk) != null && num(after?.balanceIsk) != null) {
     charged = Math.round((before.balanceIsk - after.balanceIsk) * 100) / 100;
   }
-  const units = num(b.units);
-  const unitsText = units != null ? ` · ${formatInt(units)} einingar` : "";
+  const chars = charsOf([b, data], "characters", "units", perWord(b, data, after, before));
+  const charsText = chars ? ` · ${chars.approx ? "um " : ""}${formatChars(chars.n)}` : "";
   const lines = [];
-  if (charged == null) lines.push(`- Þetta kall: kostnaður óþekktur${unitsText}`);
-  else if (charged < 0) lines.push(`- Þetta kall: ekki hægt að reikna (inneignin breyttist á meðan)${unitsText}`);
+  if (charged == null) lines.push(`- Þetta kall: kostnaður óþekktur${charsText}`);
+  else if (charged < 0) lines.push(`- Þetta kall: ekki hægt að reikna (inneignin breyttist á meðan)${charsText}`);
   else if (charged === 0) lines.push(b.paidFrom === "credit"
-    ? `- Þetta kall: 0 kr. af inneign${unitsText}`
-    : `- Þetta kall: 0 kr., ókeypis dagskammtur${unitsText}`);
-  else lines.push(`- Þetta kall: ${formatIsk(charged)} af inneign${exact ? "" : " (mismunur á inneign fyrir og eftir)"}${unitsText}`);
+    ? `- Þetta kall: 0 kr. af inneign${charsText}`
+    : `- Þetta kall: 0 kr., ókeypis dagskammtur${charsText}`);
+  else lines.push(`- Þetta kall: ${formatIsk(charged)} af inneign${exact ? "" : " (mismunur á inneign fyrir og eftir)"}${charsText}`);
 
   const balance = num(b.balanceIsk) ?? num(after?.balanceIsk);
-  const left = num(b.freeUnitsLeftToday) ?? num(after?.freeUnitsLeftToday);
-  const daily = num(after?.freeDailyUnits) ?? num(before?.freeDailyUnits);
+  const free = freeCharsText(b, after, before);
   const parts = [];
   if (balance != null) parts.push(`inneign ${formatIsk(balance)}`);
-  if (left != null && daily != null) parts.push(`ókeypis eftir í dag ${formatInt(left)} af ${formatInt(daily)} einingum`);
-  else if (left != null) parts.push(`ókeypis eftir í dag ${formatInt(left)} einingar`);
-  else if (daily != null && daily > 0) parts.push(`ókeypis ${formatInt(daily)} einingar á dag`);
+  if (free) parts.push(free);
   if (parts.length) lines.push(`- Staða: ${parts.join(" · ")}`);
   else lines.push("- Staða: náðist ekki að sækja (`npx altalandi whoami`)");
   if (balance != null && balance < 50) lines.push("- Bæta við inneign: https://altalandi.is/stjornbord/inneign");
@@ -329,6 +384,8 @@ export function batchReportMarkdown(summary) {
     `| Kaflar | ${count(t.passages)}: ${count(t.changed)} breyttir, ${count(t.unchangedPassages)} þurftu ekki breytingu, `
       + `${count(t.kept)} héldu frumtextanum, ${count(t.failed)} mistókust |`,
     `| Stafir sendir | ${count(t.characters)} |`,
+    ...(Number.isFinite(t.billedCharacters)
+      ? [`| Stafir rukkaðir | ${t.billedCharactersApprox ? "um " : ""}${count(t.billedCharacters)} |`] : []),
     `| Tegund texta | ${cell(summary?.domain || "general")} |`,
     `| Málsnið | ${cell(summary?.register || "neutral")} |`,
   ];

package/skill/SKILL.md

@@ -14,7 +14,7 @@ description: >-
 
 Altalandi rewrites English or stiff Icelandic so it reads as if a native wrote
 it, checks that the meaning held, and lists every change with its reason. Each
-call is paid from the user's free daily units or their credit.
+call is paid from the user's free daily characters or their credit.
 
 **Follow this procedure exactly, every time.** The user must always see the same
 thing: the verdict, the text before and after, each change with its reason, what
@@ -52,7 +52,7 @@ a check is rewritten once more, which can double that.
 3. **Paste its stdout into your reply exactly as printed**, as the first thing in
    your reply. It is Markdown: a verdict line, **Fyrir**, **Eftir**,
    **Breytingar** (each change and its reason), **Kostnaður** (cost of this call,
-   balance and free units left) and **Verkið**, the run's own page. Do not
+   balance and free characters left) and **Verkið**, the run's own page. Do not
    shorten, reorder, translate or reword it. The run page shows the user the
    text sent, the result and the checks, and lets them approve, reject or edit
    the result there; point them to it when they want to review the work.
@@ -70,7 +70,7 @@ a check is rewritten once more, which can double that.
    of your own.
 
 A document of several sections (more than about 3,000 characters) goes better
-through the folder run below: it sends each passage separately, two at a time,
+through the folder run below: it refines and checks each passage on its own,
 and a passage that fails keeps its original without holding up the rest. Save
 the text as a `.md` file in an empty temporary folder and run the folder steps.
 
@@ -120,10 +120,15 @@ charged at https://altalandi.is/stjornbord/notkun. With the tools:
 - **Never hand-edit the Icelandic and present it as Altalandi's.** If you think
   something should still change, say so separately under a heading such as
   "Mín tillaga (ekki yfirfarin af Altalandi)", or ask before running it again.
-- **One call per coherent text** (a page section, an email, one UI string). For
-  a few strings, run them one by one, at most 4 at a time, and paste each block.
-  Keep keys, placeholders (`{name}`, `%s`), HTML and code out of the text you send.
-  For a whole folder, i18n catalog or website, use the folder run below instead.
+- **One call per coherent text** (a page section, an email). Keep keys,
+  placeholders (`{name}`, `%s`), HTML and code out of the text you send. For a
+  whole folder, i18n catalog or website, use the folder run below instead.
+- **Many short strings** (UI strings, an i18n catalog, a list of labels or
+  messages): **never call Altalandi once per string.** Put them in a JSON file
+  (`{"key": "English text", …}`) in an empty temporary folder, or use the
+  project's existing catalog folder, and run the folder run below on that folder
+  (`--dry-run` first). It sends short strings together in batches, which is
+  cheaper and faster, and still checks each string on its own.
 - **Product names and coined words** the meaning check cannot recognise can make
   it refuse a rewrite (exit 3, "ekki tókst að staðfesta"). That is the safe
   result: keep the original and tell the user.
@@ -132,11 +137,13 @@ charged at https://altalandi.is/stjornbord/notkun. With the tools:
   writes `./altalandi-reports/altalandi-<time>-<id>.md`, and the block shows
   its path. Reports contain the text, so write them only when asked.
 - **Don't use `--fast`** for text people will read: it skips the meaning check.
+- **Cost is in characters and krónur,** as the block and the estimate show it.
+  Never work out or quote a price per 100 characters.
 - If the user only wants spelling fixed and every other word kept, use the
   `proofread_icelandic` tool where it is available. The command line rewrites:
   tell the user it may rephrase, and go through the changes with them.
 - Every call from a signed-in account is kept in that account's history for
-  90 days, so the run page can show it; only the account and its team see it,
+  as long as they keep it, so the run page can show it; only the account and its team see it,
   and it can be deleted on the page or switched off in Settings. Separately,
   free use is kept, with personal data scrubbed, to improve the service; paid
   use only with consent. Add `--no-store` when the user asks that their text
@@ -152,7 +159,7 @@ check passed.
 
 1. **Estimate first:** `npx -y altalandi@latest <folder or URL> --dry-run` (add
    `--site` for a whole site). Show the user the estimate it prints: files,
-   passages, characters, units and the price if paid from credit.
+   passages, the characters billed and the price if paid from credit.
 2. **Only when the user agrees,** run the same command with `--yes` in place of
    `--dry-run`, with the shell timeout set to 10 minutes or in the background.
    The result goes to `<folder>-is` unless they name a place (`--out <path>`).
@@ -169,12 +176,12 @@ Only when a call exits with 2 (`Not logged in`):
    minutes.
 2. As soon as it prints a link (`https://altalandi.is/tengja?kodi=XXXX-XXXX`) and
    a code, show both to the user. Tell them to sign in or create an account
-   (2,000 free units a day, and 500 kr. of trial credit once they confirm their email) and
+   (a free daily allowance of characters, and 500 kr. of trial credit once they confirm their email) and
    click **Tengja**.
 3. When it prints `✓ Tengt sem <username>`, run step 2 of the procedure again.
 
 Never ask the user for an API key, and do not tell them to set
 `ALTALANDI_API_KEY`. `npx -y altalandi@latest whoami` shows the account, the
-balance and the free units at any time.
+balance and the free characters left today at any time.
 
 Docs for building the API into an app: https://altalandi.is/agents.md

package/update.mjs

@@ -140,6 +140,8 @@ export const SHIPPED_SKILLS = new Set([
   "f7de208557f519a4", // 0.4.0
   "4bd64565d251641e", // 0.5.0
   "aeb88010599539fd", // 0.6.0
+  "ebfc4ef17a614973", // 0.6.1
+  "9def55ecc6b30785", // 0.6.2
 ]);
 
 export function skillFingerprint(text) {