tinydecide 0.0.0-stage → 0.1.2

package/src/model.js

@@ -0,0 +1,154 @@
+// The compiled model: hashed feature rows (int8, one scale per row) → two mean pools → linear head.
+// A .tdm file is: "TDM1", u32 header length, JSON header (padded to 4 bytes), then the arrays.
+
+import { FEATURES_VERSION, Featurizer } from './features.js';
+import { U32Map } from './hash.js';
+
+const MAGIC = [0x54, 0x44, 0x4d, 0x31]; // TDM1
+
+export class Model {
+  /**
+   * @param {object} p
+   * @param {string[]} p.labels
+   * @param {number} p.d            row width
+   * @param {Uint32Array} p.keys    feature hash per row
+   * @param {Float32Array} p.scales per-row dequantization scale
+   * @param {Int8Array} p.q         rows, keys.length × d
+   * @param {Float32Array} p.W      head, labels.length × d
+   * @param {Float32Array} p.b      bias, labels.length
+   * @param {number} [p.T]          temperature for reported confidence
+   * @param {number} [p.cutoff]     answer locally when the top-two logit margin ≥ cutoff
+   * @param {object} [p.meta]       certificate and compile report summary
+   */
+  constructor({ labels, d, keys, scales, q, W, b, T = 1, cutoff = Infinity, meta = {} }) {
+    Object.assign(this, { labels, d, keys, scales, q, W, b, T, cutoff, meta });
+    this.K = labels.length;
+    this.index = new U32Map(keys.length);
+    for (let i = 0; i < keys.length; i++) this.index.set(keys[i], i);
+    this.fz = new Featurizer();
+    this.h = new Float32Array(d);
+    this.tmp = new Float32Array(d);
+    this.z = new Float32Array(this.K);
+  }
+
+  /** Raw logits for an input. The returned array is reused by the next call. */
+  logits(input) {
+    const { w, c } = this.fz.run(input);
+    const { d, K, h, z, W, b } = this;
+    h.fill(0);
+    this.#pool(w); this.#pool(c);
+    for (let k = 0; k < K; k++) {
+      let s = b[k];
+      const o = k * d;
+      for (let j = 0; j < d; j++) s += W[o + j] * h[j];
+      z[k] = s;
+    }
+    return z;
+  }
+
+  #pool(feats) {
+    const { d, index, q, scales, h, tmp } = this;
+    tmp.fill(0);
+    let n = 0;
+    for (let i = 0; i < feats.length; i++) {
+      const r = index.get(feats[i]);
+      if (r < 0) continue;
+      n++;
+      const s = scales[r], o = r * d;
+      for (let j = 0; j < d; j++) tmp[j] += q[o + j] * s;
+    }
+    if (n) for (let j = 0; j < d; j++) h[j] += tmp[j] / n;
+  }
+
+  /**
+   * @returns {{ choice: string, index: number, confidence: number, margin: number, local: boolean, probs?: Record<string, number> }}
+   */
+  decide(input, { probs = false } = {}) {
+    const z = this.logits(input);
+    const { top, second } = topTwo(z);
+    const margin = second < 0 ? Infinity : z[top] - z[second];
+    const p = softmax(z, this.T);
+    const out = { choice: this.labels[top], index: top, confidence: p[top], margin, local: margin >= this.cutoff };
+    if (probs) out.probs = Object.fromEntries(this.labels.map((l, k) => [l, p[k]]));
+    return out;
+  }
+
+  /** A copy that answers with a different cutoff (e.g. Infinity to send everything to your API). */
+  withCutoff(cutoff) {
+    return new Model({ ...this, cutoff });
+  }
+
+  get bytes() {
+    return this.keys.byteLength + this.scales.byteLength + this.q.byteLength + this.W.byteLength + this.b.byteLength;
+  }
+
+  toBytes() {
+    const header = new TextEncoder().encode(JSON.stringify({
+      format: 1, features: FEATURES_VERSION, labels: this.labels, d: this.d, n: this.keys.length,
+      T: this.T, cutoff: Number.isFinite(this.cutoff) ? this.cutoff : null, meta: this.meta,
+    }));
+    const hlen = (header.length + 3) & ~3;
+    const parts = [this.keys, this.scales, this.W, this.b, this.q];
+    const body = parts.reduce((s, a) => s + a.byteLength, 0);
+    const out = new Uint8Array(8 + hlen + body);
+    out.set(MAGIC, 0);
+    new DataView(out.buffer).setUint32(4, header.length, true);
+    out.set(header, 8);
+    out.fill(0x20, 8 + header.length, 8 + hlen);
+    let o = 8 + hlen;
+    for (const a of parts) { out.set(new Uint8Array(a.buffer, a.byteOffset, a.byteLength), o); o += a.byteLength; }
+    return out;
+  }
+
+  static fromBytes(bytes) {
+    const u8 = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    if (MAGIC.some((m, i) => u8[i] !== m)) throw new Error('not a tinydecide model (bad magic)');
+    const len = new DataView(u8.buffer, u8.byteOffset, u8.byteLength).getUint32(4, true);
+    const h = JSON.parse(new TextDecoder().decode(u8.subarray(8, 8 + len)));
+    if (h.format !== 1) throw new Error(`unsupported model format ${h.format}`);
+    if (h.features !== FEATURES_VERSION) throw new Error(`model needs featurizer v${h.features}, this build has v${FEATURES_VERSION}`);
+    const K = h.labels.length;
+    // Copy the body into a fresh buffer: typed-array views need alignment, and a Node Buffer's
+    // .slice() is a view into a shared pool, not a copy.
+    const body = new Uint8Array(u8.byteLength - (8 + ((len + 3) & ~3)));
+    body.set(u8.subarray(8 + ((len + 3) & ~3)));
+    const buf = body.buffer;
+    let o = 0;
+    const take = (Ctor, n) => { const a = new Ctor(buf, o, n); o += n * Ctor.BYTES_PER_ELEMENT; return a; };
+    const keys = take(Uint32Array, h.n), scales = take(Float32Array, h.n);
+    const W = take(Float32Array, K * h.d), b = take(Float32Array, K), q = take(Int8Array, h.n * h.d);
+    return new Model({ labels: h.labels, d: h.d, keys, scales, q, W, b, T: h.T, cutoff: h.cutoff ?? Infinity, meta: h.meta });
+  }
+}
+
+export function topTwo(z) {
+  let top = 0, second = -1;
+  for (let k = 1; k < z.length; k++) {
+    if (z[k] > z[top]) { second = top; top = k; } else if (second < 0 || z[k] > z[second]) second = k;
+  }
+  return { top, second };
+}
+
+export function softmax(z, T = 1) {
+  let m = -Infinity;
+  for (let k = 0; k < z.length; k++) if (z[k] > m) m = z[k];
+  const p = new Float64Array(z.length);
+  let s = 0;
+  for (let k = 0; k < z.length; k++) s += p[k] = Math.exp((z[k] - m) / T);
+  for (let k = 0; k < z.length; k++) p[k] /= s;
+  return p;
+}
+
+/** Per-row symmetric int8 quantization of float training parameters. */
+export function quantize({ labels, d, keys, E, W, b }, extra = {}) {
+  const n = keys.length;
+  const q = new Int8Array(n * d), scales = new Float32Array(n);
+  for (let r = 0; r < n; r++) {
+    let m = 0;
+    for (let j = 0; j < d; j++) m = Math.max(m, Math.abs(E[r * d + j]));
+    const s = m / 127 || 1;
+    scales[r] = m ? s : 0;
+    for (let j = 0; j < d; j++) q[r * d + j] = Math.round(E[r * d + j] / s);
+  }
+  return new Model({ labels, d, keys, scales, q, W: Float32Array.from(W), b: Float32Array.from(b), ...extra });
+}

package/src/node.js

@@ -0,0 +1,210 @@
+// The Node entry. Same API as the browser build, plus:
+//   - shadow('name', api) keeps answers, the model and its state in .tinydecide/name/, so a restart
+//     resumes where it left off
+//   - compiles train in a worker thread, off your server's event loop
+
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, writeSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { Worker } from 'node:worker_threads';
+import { gunzipSync } from 'node:zlib';
+import { compile } from './compile.js';
+import { logger } from './log.js';
+import { Model } from './model.js';
+import { NAME, shadow as core, validate } from './shadow.js';
+import { memoryStore } from './store.js';
+import { abortError } from './train.js';
+
+export * from './index.js';
+
+/**
+ * shadow('support', api, options): in Node, a named decision is saved under `dir` (default
+ * .tinydecide, or $TINYDECIDE_DIR) and resumes after a restart.
+ */
+export function shadow(name, api, options) {
+  if (typeof name === 'function') return core(name, { compiler: compileInWorker, ...api });
+  const { dir = process.env.TINYDECIDE_DIR || '.tinydecide', ...rest } = options ?? {};
+  if (typeof name !== 'string' || !NAME.test(name)) return core(name, api, rest); // core explains the error
+  validate(name, api, rest); // before anything touches the disk
+  let store = rest.store;
+  if (!store) {
+    try {
+      store = fileStore(join(dir, name));
+    } catch (err) {
+      // A folder that can't be written, or that another process holds, must not stop the app.
+      store = memoryStore();
+      logger(name, rest.log ?? true)({ type: 'error', where: `opening ${join(dir, name)}`, error: `${err.message}. Answers stay in memory.` });
+    }
+  }
+  return core(name, api, { compiler: compileInWorker, ...rest, store });
+}
+
+/**
+ * Keeps one decision in a folder:
+ *   answers.jsonl  your API's recent answers (trimmed to the newest `limit`)
+ *   model.tdm      the installed model, and report.json, its compile report
+ *   state.json     present only while guarded
+ *   lock           the pid of the process using the folder; a second store on it throws
+ * Writes of the model and state are atomic.
+ */
+export function fileStore(dir, { limit = 100_000 } = {}) {
+  const root = dirname(dir);
+  const fresh = !existsSync(root);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  // The log holds raw inputs, so keep the whole folder out of git unless someone opts in.
+  if (fresh) safeWrite(join(root, '.gitignore'), '# created by tinydecide: answers.jsonl holds raw inputs\n*\n');
+  const path = { answers: join(dir, 'answers.jsonl'), model: join(dir, 'model.tdm'), report: join(dir, 'report.json'), state: join(dir, 'state.json'), lock: resolve(dir, 'lock') };
+  takeLock(path.lock);
+  let fd = -1, size = 0;
+
+  function open() {
+    size = 0;
+    if (existsSync(path.answers)) {
+      const buf = readFileSync(path.answers);
+      for (let i = 0; i < buf.length; i++) if (buf[i] === 10) size++;
+      // A crash mid-write can leave a partial last line; end it so the next answer starts clean.
+      if (buf.length && buf[buf.length - 1] !== 10) writeFileSync(path.answers, '\n', { flag: 'a' });
+    }
+    fd = openSync(path.answers, 'a', 0o600);
+  }
+  open();
+
+  /** Keeps the newest `limit` lines. Scans bytes for newlines, so nothing is parsed. */
+  function trim() {
+    const buf = readFileSync(path.answers);
+    let at = buf.length - 1; // the newline that ends the last line
+    for (let k = 0; k < limit && at > 0; k++) at = buf.lastIndexOf(10, at - 1);
+    closeSync(fd); // first: Windows will not rename over a file that is still open
+    fd = -1;
+    try {
+      atomicWrite(path.answers, buf.subarray(at + 1));
+    } finally {
+      open();
+      size = Math.min(size, limit); // after a failure, wait another quarter of `limit` before retrying
+    }
+  }
+
+  return {
+    dir,
+    append(record) {
+      writeSync(fd, JSON.stringify(record) + '\n');
+      if (++size > limit * 1.25) trim();
+    },
+    load: () => readJsonl(path.answers).slice(-limit),
+    get size() { return size; },
+    loadModel: () => (existsSync(path.model) ? Model.fromBytes(readFileSync(path.model)) : null),
+    saveModel(model, report) {
+      atomicWrite(path.model, model.toBytes());
+      atomicWrite(path.report, JSON.stringify(report, null, 2) + '\n');
+    },
+    loadState() {
+      if (!existsSync(path.state)) return null;
+      try { return JSON.parse(readFileSync(path.state, 'utf8')); } catch { return null; }
+    },
+    saveState(state) {
+      if (state) atomicWrite(path.state, JSON.stringify(state) + '\n');
+      else rmSync(path.state, { force: true });
+    },
+    close() {
+      if (fd < 0) return;
+      closeSync(fd);
+      fd = -1;
+      rmSync(path.lock, { force: true });
+      held.delete(path.lock);
+    },
+  };
+}
+
+const held = new Set(); // lock files this process holds
+
+/** One process per folder: a second writer would lose answers when the log is trimmed. */
+function takeLock(path) {
+  if (held.has(path)) throw new Error(`${dirname(path)} is already open in this process`);
+  try {
+    writeFileSync(path, String(process.pid), { flag: 'wx', mode: 0o600 });
+  } catch (err) {
+    if (err.code !== 'EEXIST') throw err;
+    const pid = Number(readFileSync(path, 'utf8'));
+    // Our own pid here means an earlier run left it, as when a container restarts with the same pid.
+    if (pid && pid !== process.pid && alive(pid)) {
+      throw new Error(`${dirname(path)} is in use by process ${pid}. Use one process per folder, or delete ${path} if that process is not using it`);
+    }
+    rmSync(path, { force: true }); // stale: the process that wrote it is gone
+    writeFileSync(path, String(process.pid), { flag: 'wx', mode: 0o600 });
+  }
+  held.add(path);
+}
+
+function alive(pid) {
+  try { process.kill(pid, 0); return true; } catch (err) { return err.code === 'EPERM'; }
+}
+
+let workerBroken = false;
+
+/** compile() in a worker thread. Falls back to the calling thread if workers are unavailable. */
+function compileInWorker(rows, options = {}) {
+  const { signal, onProgress, background, ...rest } = options;
+  if (workerBroken) return compile(rows, { ...rest, signal, onProgress });
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(abortError());
+    let settled = false;
+    const done = (fn, v) => { if (!settled) { settled = true; signal?.removeEventListener('abort', abort); fn(v); } };
+    let worker;
+    try {
+      worker = new Worker(new URL('./worker.js', import.meta.url), { workerData: { rows, options: rest } });
+    } catch {
+      workerBroken = true;
+      return compile(rows, { ...rest, signal, onProgress }).then(resolve, reject);
+    }
+    if (background) worker.unref(); // an automatic compile never keeps a finished process alive
+    function abort() { worker.terminate(); done(reject, abortError()); }
+    signal?.addEventListener('abort', abort, { once: true });
+    worker.once('message', (m) => {
+      if (m.error) return done(reject, Object.assign(new Error(m.error.message), { name: m.error.name }));
+      done(resolve, { model: Model.fromBytes(m.bytes), report: m.report });
+    });
+    let fallback = false;
+    worker.once('error', (err) => {
+      // The worker could not start (a bundler that drops worker.js, say): compile here instead.
+      if (['ERR_WORKER_PATH', 'ERR_MODULE_NOT_FOUND', 'ERR_WORKER_INIT_FAILED'].includes(err?.code)) {
+        workerBroken = fallback = true;
+        compile(rows, { ...rest, signal, onProgress }).then((v) => done(resolve, v), (e) => done(reject, e));
+      } else done(reject, err);
+    });
+    worker.once('exit', (code) => { if (!fallback) done(reject, new Error(`the compile worker exited with code ${code}`)); });
+  });
+}
+
+/** Reads a .jsonl or .jsonl.gz file. Lines that are not valid JSON (a crash mid-write) are skipped. */
+export function readJsonl(path, { onSkip } = {}) {
+  if (!existsSync(path)) return [];
+  let buf = readFileSync(path);
+  if (path.endsWith('.gz')) buf = gunzipSync(buf);
+  const out = [];
+  let line = 0;
+  for (const raw of buf.toString('utf8').split('\n')) {
+    line++;
+    const s = raw.trim();
+    if (!s) continue;
+    try { out.push(JSON.parse(s)); } catch { onSkip?.(line); }
+  }
+  return out;
+}
+
+export function loadModel(path) {
+  return Model.fromBytes(readFileSync(path));
+}
+
+export function saveModel(path, model) {
+  mkdirSync(dirname(path), { recursive: true });
+  atomicWrite(path, model.toBytes());
+}
+
+function atomicWrite(path, data) {
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, data, { mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+function safeWrite(path, data) {
+  try { writeFileSync(path, data, { flag: 'wx' }); } catch {}
+}