aeacus-cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# Aeacus CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`aeacus` reads a text file or standard input, scores it with the published Aeacus model, and prints a verdict. The first run downloads the model, tokenizer, and calibration settings (about 82 MB) from Hugging Face and caches them under `~/.cache/aeacus/`.
+
+```sh
+cat draft.txt | aeacus
+aeacus draft.txt
+aeacus draft.txt --json
+```
+
+Default output is a short summary with excerpts of likely AI regions. Regions combine adjacent tokens with the same classification. `--json` emits one JSON object, including grouped regions with character offsets, scores, and excerpts. `--porcelain` emits stable tab-separated summary fields.
+
+The document `ai_score` is the mean calibrated score across tokens. It is an AI-likeness heuristic, not a probability of authorship. A score at or above 0.5 is `ai_leaning`; below 0.5 is `human_leaning`. Text under 30 words is `insufficient_text`, since the model was trained on longer passages. Per-token regions use the model's calibrated thresholds and may be `likely_ai`, `likely_human`, or `uncertain`.
+
+The CLI runs on CPU. Use `--model-dir` to point to a local model directory containing `tokenizer.json`, `thresholds.json`, and `onnx/model_q4f16.onnx`. `AEACUS_CACHE_DIR` overrides the default model cache location.
+
+This package will be published to npm as `aeacus-cli`, exposing the command `aeacus`. The CLI package has no license declaration. Publish its first version once from an npm-authenticated environment, then configure npm Trusted Publishing for this repository and `.github/workflows/publish-cli.yml`. Later releases build a package archive and publish when a matching `cli-v<version>` tag is pushed.

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "aeacus-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Check writing with the Aeacus human-vs-AI classifier",
+  "repository": "git+https://github.com/SeriousBug/aeacus.git",
+  "type": "module",
+  "bin": {
+    "aeacus": "./src/cli.js"
+  },
+  "files": [
+    "src/"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "onnxruntime-node": "1.30.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import ort from "onnxruntime-node";
+import { Tokenizer } from "./tokenizer.js";
+
+const REVISION = "57d4ce806931beff3d0150f74f330b831a9efb80";
+const MODEL_FILES = ["tokenizer.json", "thresholds.json", "onnx/model_q4f16.onnx"];
+const WINDOW = 510;
+const STRIDE = 128;
+
+function usage() {
+  return `Usage: aeacus [file] [--json|--porcelain] [--model-dir directory]
+
+Read text from a file or stdin and estimate how AI-like its writing is.
+
+Options:
+  --json             Output a JSON object for agents and scripts
+  --porcelain        Output stable tab-separated summary fields
+  --model-dir PATH   Use a local folder with tokenizer.json, thresholds.json,
+                     and onnx/model_q4f16.onnx
+  -h, --help         Show this help
+
+Examples:
+  cat draft.txt | aeacus
+  aeacus draft.txt --json
+  cat draft.txt | aeacus --porcelain`;
+}
+
+function parseArgs(args) {
+  const opts = { format: "text", modelDir: null, input: null };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--json") opts.format = "json";
+    else if (arg === "--porcelain") opts.format = "porcelain";
+    else if (arg === "--model-dir") {
+      if (!args[i + 1]) throw new Error("--model-dir requires a path");
+      opts.modelDir = path.resolve(args[++i]);
+    } else if (arg === "-h" || arg === "--help") opts.help = true;
+    else if (arg.startsWith("-")) throw new Error(`Unknown option: ${arg}`);
+    else if (opts.input) throw new Error("Provide one input file, or pipe text through stdin");
+    else opts.input = arg;
+  }
+  return opts;
+}
+
+function cacheDir() {
+  return process.env.AEACUS_CACHE_DIR
+    ? path.resolve(process.env.AEACUS_CACHE_DIR)
+    : path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"), "aeacus", REVISION);
+}
+
+async function ensureFile(root, relative) {
+  const file = path.join(root, relative);
+  try {
+    await fs.access(file);
+    return file;
+  } catch {
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const url = `https://huggingface.co/level20tauren/aeacus-s-1/resolve/${REVISION}/${relative}`;
+    process.stderr.write(`Downloading ${relative} from the Aeacus model repository…\n`);
+    const response = await fetch(url, { redirect: "follow" });
+    if (!response.ok) throw new Error(`Model download failed (${response.status}): ${relative}`);
+    const temp = `${file}.${process.pid}.tmp`;
+    await fs.writeFile(temp, Buffer.from(await response.arrayBuffer()));
+    await fs.rename(temp, file);
+    return file;
+  }
+}
+
+async function loadModel(modelDir) {
+  const root = modelDir ?? cacheDir();
+  const files = await Promise.all(MODEL_FILES.map((file) => ensureFile(root, file)));
+  const [tokenizerJson, thresholds] = await Promise.all([
+    fs.readFile(files[0], "utf8").then(JSON.parse),
+    fs.readFile(files[1], "utf8").then(JSON.parse),
+  ]);
+  const session = await ort.InferenceSession.create(files[2], { executionProviders: ["cpu"] });
+  return { tokenizer: new Tokenizer(tokenizerJson), thresholds, session };
+}
+
+async function readInput(file) {
+  if (file) return fs.readFile(file, "utf8");
+  if (process.stdin.isTTY) throw new Error("Provide a file or pipe text to aeacus on stdin");
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function calibrate(value, knots) {
+  const { x, y } = knots;
+  if (value <= x[0]) return y[0];
+  for (let i = 1; i < x.length; i++) {
+    if (value <= x[i]) {
+      const t = (value - x[i - 1]) / (x[i] - x[i - 1] || 1);
+      return y[i - 1] + t * (y[i] - y[i - 1]);
+    }
+  }
+  return y.at(-1);
+}
+
+function classification(score, thresholds) {
+  if (score >= thresholds.high) return "likely_ai";
+  if (score <= thresholds.low) return "likely_human";
+  return "uncertain";
+}
+
+function regions(text, encoded, probabilities, thresholds) {
+  const result = [];
+  for (let i = 0; i < probabilities.length; i++) {
+    const verdict = classification(probabilities[i], thresholds);
+    const previous = result.at(-1);
+    if (previous && previous.verdict === verdict) {
+      previous.end = encoded.ends[i];
+      previous.ai_score = (previous.ai_score * previous.tokens + probabilities[i]) / (previous.tokens + 1);
+      previous.tokens++;
+    } else {
+      result.push({ start: encoded.starts[i], end: encoded.ends[i], verdict,
+        ai_score: probabilities[i], tokens: 1 });
+    }
+  }
+  return result.map((region) => ({
+    ...region,
+    ai_score: Number(region.ai_score.toFixed(4)),
+    text: text.slice(region.start, region.end),
+  }));
+}
+
+async function score(text, model) {
+  const encoded = model.tokenizer.encode(text);
+  const sums = new Float64Array(encoded.ids.length);
+  const counts = new Uint16Array(encoded.ids.length);
+  const windowCount = Math.max(1, Math.ceil(Math.max(0, encoded.ids.length - WINDOW) / (WINDOW - STRIDE)) + 1);
+  for (let w = 0; w < windowCount; w++) {
+    const from = w * (WINDOW - STRIDE);
+    const to = Math.min(from + WINDOW, encoded.ids.length);
+    const input = BigInt64Array.from([model.tokenizer.clsId, ...encoded.ids.slice(from, to), model.tokenizer.sepId], BigInt);
+    const mask = new BigInt64Array(input.length).fill(1n);
+    const out = await model.session.run({
+      input_ids: new ort.Tensor("int64", input, [1, input.length]),
+      attention_mask: new ort.Tensor("int64", mask, [1, input.length]),
+    });
+    const logits = out.logits.data;
+    for (let i = from; i < to; i++) {
+      const k = (i - from + 1) * 2;
+      const raw = 1 / (1 + Math.exp(logits[k] - logits[k + 1]));
+      sums[i] += raw;
+      counts[i]++;
+    }
+    out.logits.dispose?.();
+  }
+  const probabilities = Array.from(sums, (sum, i) => calibrate(sum / counts[i], model.thresholds.calibration));
+  const aiScore = probabilities.length
+    ? probabilities.reduce((sum, probability) => sum + probability, 0) / probabilities.length
+    : null;
+  const wordCount = (text.match(/\S+/g) ?? []).length;
+  const verdict = wordCount < 30 ? "insufficient_text"
+    : aiScore >= 0.5 ? "ai_leaning" : "human_leaning";
+  return {
+    verdict,
+    ai_score: aiScore === null ? null : Number(aiScore.toFixed(4)),
+    words: wordCount,
+    tokens: probabilities.length,
+    regions: regions(text, encoded, probabilities, model.thresholds),
+    thresholds: { likely_human: model.thresholds.low, likely_ai: model.thresholds.high },
+    note: "ai_score is the mean calibrated token score, not a probability of authorship. The verdict is a heuristic; short texts are marked insufficient.",
+  };
+}
+
+function printResult(result, format) {
+  if (format === "json") {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } else if (format === "porcelain") {
+    process.stdout.write(`verdict\t${result.verdict}\nai_score\t${result.ai_score ?? "null"}\nwords\t${result.words}\ntokens\t${result.tokens}\n`);
+  } else {
+    const score = result.ai_score === null ? "unavailable" : `${Math.round(result.ai_score * 100)}%`;
+    process.stdout.write(`Aeacus: ${result.verdict.replaceAll("_", " ")} (AI-like score ${score}; ${result.words} words)\n`);
+    const likelyAi = result.regions.filter((r) => r.verdict === "likely_ai");
+    if (likelyAi.length) {
+      process.stdout.write("Likely AI regions:\n");
+      for (const region of likelyAi) {
+        const excerpt = region.text.replace(/\s+/g, " ").trim();
+        process.stdout.write(`  ${Math.round(region.ai_score * 100)}%  ${excerpt}\n`);
+      }
+    }
+    if (result.verdict === "insufficient_text") process.stdout.write("The model was trained on passages of at least 30 words.\n");
+  }
+}
+
+try {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    process.stdout.write(`${usage()}\n`);
+  } else {
+    const text = (await readInput(opts.input)).normalize("NFC");
+    const model = await loadModel(opts.modelDir);
+    printResult(await score(text, model), opts.format);
+  }
+} catch (error) {
+  process.stderr.write(`aeacus: ${error.message}\n`);
+  process.exitCode = 2;
+}

package/src/tokenizer.js

@@ -0,0 +1,112 @@
+// Byte-level BPE tokenizer matching the model's tokenizer.json.
+const PRETOKENIZE = /'s|'t|'re|'ve|'m|'ll|'d| ?\p{L}+| ?\p{N}+| ?[^\s\p{L}\p{N}]+|\s+(?!\S)|\s+/gu;
+
+function byteToUnicode() {
+  const bytes = [];
+  for (let b = 33; b <= 126; b++) bytes.push(b);
+  for (let b = 161; b <= 172; b++) bytes.push(b);
+  for (let b = 174; b <= 255; b++) bytes.push(b);
+  const chars = bytes.slice();
+  let n = 0;
+  for (let b = 0; b < 256; b++) {
+    if (!bytes.includes(b)) {
+      bytes.push(b);
+      chars.push(256 + n++);
+    }
+  }
+  const map = new Array(256);
+  bytes.forEach((b, i) => { map[b] = String.fromCharCode(chars[i]); });
+  return map;
+}
+
+export class Tokenizer {
+  constructor(json) {
+    this.vocab = new Map(Object.entries(json.model.vocab));
+    this.ranks = new Map(json.model.merges.map((m, i) => [Array.isArray(m) ? m.join(" ") : m, i]));
+    this.added = new Map(json.added_tokens.map((t) => [t.content, t.id]));
+    const escaped = [...this.added.keys()].sort((a, b) => b.length - a.length)
+      .map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+    this.addedPattern = new RegExp(escaped.join("|"), "g");
+    this.byteChars = byteToUnicode();
+    this.cache = new Map();
+    this.clsId = this.added.get("[CLS]");
+    this.sepId = this.added.get("[SEP]");
+  }
+
+  encode(text) {
+    const ids = [], starts = [], ends = [];
+    let pos = 0;
+    const plain = (end) => {
+      if (end > pos) this.#encodePlain(text, pos, end, ids, starts, ends);
+    };
+    for (const m of text.matchAll(this.addedPattern)) {
+      plain(m.index);
+      ids.push(this.added.get(m[0]));
+      starts.push(m.index);
+      ends.push(m.index + m[0].length);
+      pos = m.index + m[0].length;
+    }
+    plain(text.length);
+    return { ids, starts, ends };
+  }
+
+  #encodePlain(text, from, to, ids, starts, ends) {
+    const segment = text.slice(from, to);
+    const encoder = new TextEncoder();
+    for (const m of segment.matchAll(PRETOKENIZE)) {
+      const piece = m[0];
+      const byteChar = [];
+      let chars = "";
+      for (let i = 0; i < piece.length;) {
+        const cp = piece.codePointAt(i);
+        const width = cp > 0xffff ? 2 : 1;
+        for (const b of encoder.encode(String.fromCodePoint(cp))) {
+          byteChar.push([i, width]);
+          chars += this.byteChars[b];
+        }
+        i += width;
+      }
+      const base = from + m.index;
+      let byte = 0;
+      for (const token of this.#bpe(chars)) {
+        const first = byteChar[byte];
+        const last = byteChar[byte + token.length - 1];
+        ids.push(this.vocab.get(token));
+        starts.push(base + first[0]);
+        ends.push(base + last[0] + last[1]);
+        byte += token.length;
+      }
+    }
+  }
+
+  #bpe(word) {
+    const cached = this.cache.get(word);
+    if (cached) return cached;
+    let parts = [...word];
+    while (parts.length > 1) {
+      let best = -1, bestRank = Infinity;
+      for (let i = 0; i < parts.length - 1; i++) {
+        const rank = this.ranks.get(parts[i] + " " + parts[i + 1]);
+        if (rank !== undefined && rank < bestRank) {
+          bestRank = rank;
+          best = i;
+        }
+      }
+      if (best < 0) break;
+      const merged = parts[best] + parts[best + 1];
+      const next = [];
+      for (let i = 0; i < parts.length; i++) {
+        if (i < parts.length - 1 && parts[i] + parts[i + 1] === merged
+            && this.ranks.get(parts[i] + " " + parts[i + 1]) === bestRank) {
+          next.push(merged);
+          i++;
+        } else {
+          next.push(parts[i]);
+        }
+      }
+      parts = next;
+    }
+    if (this.cache.size < 50000) this.cache.set(word, parts);
+    return parts;
+  }
+}