@swapai/core 0.1.0

package/dist/index.js

@@ -0,0 +1,1682 @@
+import {
+  SwapAIError
+} from "./chunk-SXECHZ3L.js";
+
+// src/classifier.ts
+import { randomUUID as randomUUID2 } from "crypto";
+import { join as join3 } from "path";
+
+// src/config.ts
+function invalidConfiguration(message) {
+  throw new SwapAIError("invalid_configuration", message);
+}
+function requirePositiveInteger(value, field) {
+  if (!Number.isInteger(value) || value <= 0) {
+    invalidConfiguration(`${field} must be a positive integer`);
+  }
+}
+function requireNonNegativeInteger(value, field) {
+  if (!Number.isInteger(value) || value < 0) {
+    invalidConfiguration(`${field} must be a non-negative integer`);
+  }
+}
+function normalizeAcceptableError(value) {
+  let normalized;
+  if (typeof value === "number") {
+    normalized = value;
+  } else {
+    const match = /^\s*(\d+(?:\.\d+)?)%\s*$/.exec(value);
+    if (match === null) {
+      invalidConfiguration(
+        'acceptableError must be a number or a percentage such as "10%"'
+      );
+    }
+    normalized = Number(match[1]) / 100;
+  }
+  if (!Number.isFinite(normalized) || normalized < 0 || normalized > 1) {
+    invalidConfiguration("acceptableError must be between 0 and 1");
+  }
+  return normalized;
+}
+function validateResultConfig(result) {
+  if (result.type === "number") {
+    if (!Number.isFinite(result.min) || !Number.isFinite(result.max)) {
+      invalidConfiguration("number result bounds must be finite");
+    }
+    if (result.max <= result.min) {
+      invalidConfiguration("number result max must be greater than min");
+    }
+    return;
+  }
+  if (result.type === "string") {
+    if (result.values.length === 0) {
+      invalidConfiguration("string result values must not be empty");
+    }
+    if (result.values.some((value) => typeof value !== "string") || new Set(result.values).size !== result.values.length) {
+      invalidConfiguration("string result values must be unique strings");
+    }
+  }
+}
+function normalizeConfig(config) {
+  if (typeof config.name !== "string" || config.name.trim() === "") {
+    invalidConfiguration("name must not be empty");
+  }
+  validateResultConfig(config.result);
+  requirePositiveInteger(config.retrainOnCount, "retrainOnCount");
+  requireNonNegativeInteger(config.retestInterval, "retestInterval");
+  requirePositiveInteger(config.retestRevertOn, "retestRevertOn");
+  requirePositiveInteger(config.maxTrainingSet, "maxTrainingSet");
+  if (config.maxTrainingSet < config.retrainOnCount) {
+    invalidConfiguration(
+      "maxTrainingSet must be greater than or equal to retrainOnCount"
+    );
+  }
+  if (config.model !== "needle2") {
+    invalidConfiguration('model must be "needle2"');
+  }
+  if (config.dataDirectory !== void 0 && (typeof config.dataDirectory !== "string" || config.dataDirectory.trim() === "")) {
+    invalidConfiguration("dataDirectory must not be empty");
+  }
+  if (config.onBackgroundError !== void 0 && typeof config.onBackgroundError !== "function") {
+    invalidConfiguration("onBackgroundError must be a function");
+  }
+  return {
+    ...config,
+    acceptableError: normalizeAcceptableError(config.acceptableError)
+  };
+}
+function validateResult(config, value) {
+  const valid = config.type === "number" ? typeof value === "number" && Number.isFinite(value) && value >= config.min && value <= config.max : config.type === "boolean" ? typeof value === "boolean" : typeof value === "string" && config.values.includes(value);
+  if (!valid) {
+    throw new SwapAIError(
+      "invalid_result",
+      "classification result does not match the declared allowed results"
+    );
+  }
+  return value;
+}
+
+// src/evaluation.ts
+function resultError(config, reference, candidate) {
+  const validReference = validateResult(config, reference);
+  const validCandidate = validateResult(config, candidate);
+  if (config.type === "number") {
+    return Math.abs(validReference - validCandidate) / (config.max - config.min);
+  }
+  return validReference === validCandidate ? 0 : 1;
+}
+function averageError(config, comparisons) {
+  if (comparisons.length === 0) {
+    throw new SwapAIError(
+      "invalid_result",
+      "at least one held-out example is required to calculate average error"
+    );
+  }
+  const total = comparisons.reduce(
+    (sum, comparison) => sum + resultError(config, comparison.reference, comparison.candidate),
+    0
+  );
+  return total / comparisons.length;
+}
+
+// src/runtime.ts
+import { createHash, randomUUID } from "crypto";
+import { spawn } from "child_process";
+import {
+  chmod,
+  copyFile,
+  mkdir,
+  readFile,
+  readdir,
+  stat,
+  writeFile
+} from "fs/promises";
+import { createInterface } from "readline";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+// src/needle.ts
+function createNeedleTool(config) {
+  const description = "The classification result.";
+  let result;
+  switch (config.type) {
+    case "number":
+      result = {
+        type: "number",
+        minimum: config.min,
+        maximum: config.max,
+        description
+      };
+      break;
+    case "boolean":
+      result = { type: "boolean", description };
+      break;
+    case "string":
+      result = { type: "string", enum: [...config.values], description };
+      break;
+  }
+  return {
+    name: "classify",
+    description: "Classify every supplied input and always return the learned result.",
+    parameters: {
+      type: "object",
+      properties: { result },
+      required: ["result"],
+      additionalProperties: false
+    }
+  };
+}
+function createTrainingLine(input, value, config) {
+  const result = validateNeedleResult(value, config);
+  return JSON.stringify({
+    query: input,
+    tools: [createNeedleTool(config)],
+    answers: [{ name: "classify", arguments: { result } }]
+  });
+}
+function validateNeedleResult(value, config) {
+  switch (config.type) {
+    case "number":
+      if (typeof value !== "number" || !Number.isFinite(value) || value < config.min || value > config.max) {
+        throw new TypeError(
+          `Needle returned a number outside ${config.min} to ${config.max}.`
+        );
+      }
+      return value;
+    case "boolean":
+      if (typeof value !== "boolean") {
+        throw new TypeError("Needle did not return a boolean result.");
+      }
+      return value;
+    case "string":
+      if (typeof value !== "string" || !config.values.includes(value)) {
+        throw new TypeError("Needle returned a value that is not an allowed string result.");
+      }
+      return value;
+  }
+}
+
+// src/runtime.ts
+var NEEDLE_VERSION = "2.0.14";
+var UV_VERSION = "0.11.4";
+var PYTHON_VERSION = "3.12";
+var NeedleRuntimeError = class extends SwapAIError {
+  constructor(code, message, cause) {
+    super(code, message, cause === void 0 ? void 0 : { cause });
+    this.name = "NeedleRuntimeError";
+  }
+};
+function createNeedleRuntime(options) {
+  return new ManagedNeedleRuntime(options);
+}
+var ManagedNeedleRuntime = class {
+  #dataDirectory;
+  #runtimeDirectory;
+  #runCommand;
+  #spawnProcess;
+  #fetch;
+  #workerPath;
+  #requirementsPath;
+  #onBackgroundError;
+  #models = /* @__PURE__ */ new Set();
+  #readyPromise;
+  #pythonPath;
+  #environment;
+  #closed = false;
+  constructor(options) {
+    this.#dataDirectory = options.dataDirectory;
+    this.#runtimeDirectory = join(options.dataDirectory, "runtime");
+    this.#runCommand = options.dependencies?.runCommand ?? runCommand;
+    this.#spawnProcess = options.dependencies?.spawnProcess ?? spawnProcess;
+    this.#fetch = options.dependencies?.fetch ?? globalThis.fetch;
+    this.#workerPath = options.dependencies?.workerPath ?? fileURLToPath(new URL("../python/swapai_worker.py", import.meta.url));
+    this.#requirementsPath = options.dependencies?.requirementsPath ?? fileURLToPath(new URL("../python/requirements.lock", import.meta.url));
+    this.#onBackgroundError = options.onBackgroundError;
+  }
+  ready() {
+    if (this.#closed) {
+      return Promise.reject(
+        new NeedleRuntimeError("service_unavailable", "Needle runtime is closed.")
+      );
+    }
+    this.#readyPromise ??= this.#prepare().catch((error) => {
+      this.#readyPromise = void 0;
+      throw toRuntimeError("Could not prepare Needle.", error);
+    });
+    return this.#readyPromise;
+  }
+  async train(options) {
+    if (!Number.isSafeInteger(options.generation) || options.generation < 0) {
+      throw new NeedleRuntimeError(
+        "service_unavailable",
+        "Needle generation must be a non-negative integer."
+      );
+    }
+    if (options.examples.length === 0) {
+      throw new NeedleRuntimeError(
+        "service_unavailable",
+        "Needle needs at least one training example."
+      );
+    }
+    await this.ready();
+    const classifierDirectory = join(
+      this.#dataDirectory,
+      "classifiers",
+      classifierKey(options.classifierName)
+    );
+    const generationDirectory = join(
+      classifierDirectory,
+      `generation-${options.generation}`
+    );
+    const checkpointDirectory = join(generationDirectory, "checkpoints");
+    const candidateDirectory = join(
+      generationDirectory,
+      "candidates",
+      randomUUID()
+    );
+    const trainingPath = join(candidateDirectory, "training.jsonl");
+    const modelPath = join(candidateDirectory, "model.cact");
+    await mkdir(checkpointDirectory, { recursive: true, mode: 448 });
+    await mkdir(candidateDirectory, { recursive: true, mode: 448 });
+    const lines = options.examples.map(
+      (example) => createTrainingLine(example.input, example.result, options.resultConfig)
+    );
+    await writeFile(trainingPath, `${lines.join("\n")}
+`, "utf8");
+    try {
+      await this.#runCommand(
+        this.#pythonPath,
+        [
+          this.#workerPath,
+          "train",
+          "--training-data",
+          trainingPath,
+          "--output",
+          modelPath,
+          "--checkpoint-dir",
+          checkpointDirectory,
+          "--epochs",
+          String(options.epochs ?? 10)
+        ],
+        {
+          cwd: candidateDirectory,
+          env: this.#environment,
+          timeoutMs: 6 * 60 * 60 * 1e3
+        }
+      );
+      await stat(modelPath);
+    } catch (error) {
+      throw toRuntimeError("Needle training failed.", error);
+    }
+    return { modelPath, needleVersion: NEEDLE_VERSION };
+  }
+  async loadModel(options) {
+    await this.ready();
+    try {
+      await stat(options.modelPath);
+    } catch (error) {
+      throw toRuntimeError(`Needle model does not exist: ${options.modelPath}`, error);
+    }
+    const schemaPath = `${options.modelPath}.schema.json`;
+    await writeFile(
+      schemaPath,
+      JSON.stringify([createNeedleTool(options.resultConfig)]),
+      "utf8"
+    );
+    const process2 = this.#spawnProcess(
+      this.#pythonPath,
+      [
+        "-u",
+        this.#workerPath,
+        "serve",
+        "--model",
+        options.modelPath,
+        "--schema",
+        schemaPath
+      ],
+      { cwd: dirname(options.modelPath), env: this.#environment }
+    );
+    const model = new NeedleModelProcess(
+      process2,
+      options.resultConfig,
+      (error) => this.#onBackgroundError?.(error),
+      () => this.#models.delete(model)
+    );
+    this.#models.add(model);
+    try {
+      await model.ready();
+      return model;
+    } catch (error) {
+      this.#models.delete(model);
+      process2.kill("SIGTERM");
+      throw toRuntimeError("Needle model could not start.", error);
+    }
+  }
+  async close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    await Promise.allSettled([...this.#models].map((model) => model.close()));
+    this.#models.clear();
+  }
+  async #prepare() {
+    const installDirectory = join(
+      this.#runtimeDirectory,
+      `needle-${NEEDLE_VERSION}`
+    );
+    const environmentDirectory = join(installDirectory, ".venv");
+    const markerPath = join(installDirectory, "installed.json");
+    await mkdir(installDirectory, { recursive: true });
+    const baseEnvironment = this.#makeEnvironment();
+    const uvPath = await this.#findOrInstallUv(baseEnvironment);
+    const pythonPath = pythonIn(environmentDirectory);
+    const environment = this.#makeEnvironment(uvPath, environmentDirectory);
+    if (!await exists(pythonPath)) {
+      await this.#runCommand(
+        uvPath,
+        ["venv", "--python", PYTHON_VERSION, environmentDirectory],
+        { cwd: installDirectory, env: environment, timeoutMs: 15 * 60 * 1e3 }
+      );
+    }
+    const requirementsDigest = createHash("sha256").update(await readFile(this.#requirementsPath)).digest("hex");
+    const marker = await readJson(markerPath);
+    let installRequired = marker?.needleVersion !== NEEDLE_VERSION || marker.requirementsDigest !== requirementsDigest;
+    let forceReinstall = false;
+    const healthCheck = [
+      "-c",
+      `import needle, jax, flax, optax; assert needle.__version__ == "${NEEDLE_VERSION}"`
+    ];
+    if (!installRequired) {
+      try {
+        await this.#runCommand(pythonPath, healthCheck, {
+          cwd: installDirectory,
+          env: environment,
+          timeoutMs: 6e4
+        });
+      } catch {
+        installRequired = true;
+        forceReinstall = true;
+      }
+    }
+    if (installRequired) {
+      await this.#runCommand(
+        uvPath,
+        [
+          "pip",
+          "install",
+          "--python",
+          pythonPath,
+          ...forceReinstall ? ["--reinstall"] : [],
+          "--require-hashes",
+          "--requirement",
+          this.#requirementsPath
+        ],
+        { cwd: installDirectory, env: environment, timeoutMs: 30 * 60 * 1e3 }
+      );
+      await this.#runCommand(pythonPath, healthCheck, {
+        cwd: installDirectory,
+        env: environment,
+        timeoutMs: 6e4
+      });
+      await writeFile(
+        markerPath,
+        JSON.stringify({ needleVersion: NEEDLE_VERSION, requirementsDigest }),
+        "utf8"
+      );
+    }
+    this.#pythonPath = pythonPath;
+    this.#environment = environment;
+  }
+  #makeEnvironment(uvPath, environmentDirectory) {
+    const pathParts = [
+      environmentDirectory ? dirname(pythonIn(environmentDirectory)) : void 0,
+      uvPath ? dirname(uvPath) : void 0,
+      process.env.PATH
+    ].filter((part) => Boolean(part));
+    return {
+      ...process.env,
+      PATH: pathParts.join(process.platform === "win32" ? ";" : ":"),
+      PYTHONNOUSERSITE: "1",
+      PYTHONUNBUFFERED: "1",
+      NEEDLE_TELEMETRY: "0",
+      DO_NOT_TRACK: "1",
+      HF_HOME: join(this.#runtimeDirectory, "huggingface"),
+      UV_CACHE_DIR: join(this.#runtimeDirectory, "uv-cache"),
+      XDG_CACHE_HOME: join(this.#runtimeDirectory, "cache")
+    };
+  }
+  async #findOrInstallUv(environment) {
+    const candidates = [process.env.SWAPAI_UV_PATH, "uv"].filter(
+      (candidate) => Boolean(candidate)
+    );
+    for (const candidate of candidates) {
+      try {
+        await this.#runCommand(candidate, ["--version"], {
+          env: environment,
+          timeoutMs: 3e4
+        });
+        return candidate;
+      } catch {
+      }
+    }
+    const managed = join(
+      this.#runtimeDirectory,
+      "tools",
+      process.platform === "win32" ? "uv.exe" : "uv"
+    );
+    if (!await exists(managed)) {
+      await this.#downloadUv(managed, environment);
+    }
+    await this.#runCommand(managed, ["--version"], {
+      env: environment,
+      timeoutMs: 3e4
+    });
+    return managed;
+  }
+  async #downloadUv(destination, environment) {
+    const asset = uvAsset();
+    const toolsDirectory = dirname(destination);
+    const archivePath = join(toolsDirectory, asset);
+    const extractDirectory = join(toolsDirectory, `uv-${UV_VERSION}`);
+    await mkdir(extractDirectory, { recursive: true });
+    const release = `https://github.com/astral-sh/uv/releases/download/${UV_VERSION}`;
+    const [archiveResponse, sumsResponse] = await Promise.all([
+      this.#fetch(`${release}/${asset}`, {
+        signal: AbortSignal.timeout(5 * 60 * 1e3)
+      }),
+      this.#fetch(`${release}/sha256.sum`, {
+        signal: AbortSignal.timeout(5 * 60 * 1e3)
+      })
+    ]);
+    if (!archiveResponse.ok || !sumsResponse.ok) {
+      throw new Error(`Could not download the managed uv ${UV_VERSION} binary.`);
+    }
+    const archive = Buffer.from(await archiveResponse.arrayBuffer());
+    const sums = await sumsResponse.text();
+    const expected = checksumFor(asset, sums);
+    const actual = createHash("sha256").update(archive).digest("hex");
+    if (actual !== expected) {
+      throw new Error("The managed uv download failed its SHA-256 check.");
+    }
+    await writeFile(archivePath, archive);
+    await this.#runCommand(
+      "tar",
+      [asset.endsWith(".tar.gz") ? "-xzf" : "-xf", archivePath, "-C", extractDirectory],
+      { env: environment, timeoutMs: 5 * 60 * 1e3 }
+    );
+    const extracted = await findFile(
+      extractDirectory,
+      process.platform === "win32" ? "uv.exe" : "uv"
+    );
+    if (!extracted) throw new Error("The managed uv archive did not contain uv.");
+    await copyFile(extracted, destination);
+    if (process.platform !== "win32") await chmod(destination, 493);
+  }
+};
+var NeedleModelProcess = class {
+  #process;
+  #resultConfig;
+  #onBackgroundError;
+  #onClose;
+  #pending = /* @__PURE__ */ new Map();
+  #readyPromise;
+  #exitPromise;
+  #resolveReady;
+  #rejectReady;
+  #resolveExit;
+  #requestId = 0;
+  #ready = false;
+  #exited = false;
+  #closing = false;
+  #stderr = "";
+  constructor(process2, resultConfig, onBackgroundError, onClose) {
+    this.#process = process2;
+    this.#resultConfig = resultConfig;
+    this.#onBackgroundError = onBackgroundError;
+    this.#onClose = onClose;
+    this.#readyPromise = new Promise((resolve, reject) => {
+      this.#resolveReady = resolve;
+      this.#rejectReady = reject;
+    });
+    this.#exitPromise = new Promise((resolve) => {
+      this.#resolveExit = resolve;
+    });
+    this.#listen();
+  }
+  ready() {
+    return withTimeout(
+      this.#readyPromise,
+      3e5,
+      "Needle did not become ready within five minutes."
+    );
+  }
+  classify(input) {
+    if (!this.#ready || this.#closing || this.#exited) {
+      return Promise.reject(
+        new NeedleRuntimeError("service_unavailable", "Needle model is not running.")
+      );
+    }
+    const id = ++this.#requestId;
+    const result = new Promise((resolve, reject) => {
+      this.#pending.set(id, { resolve, reject });
+      this.#process.stdin.write(
+        `${JSON.stringify({ id, type: "classify", input })}
+`,
+        (error) => {
+          if (!error) return;
+          this.#pending.delete(id);
+          reject(
+            new NeedleRuntimeError(
+              "service_unavailable",
+              "Could not send input to Needle.",
+              error
+            )
+          );
+        }
+      );
+    });
+    return withTimeout(
+      result,
+      6e4,
+      "Needle did not classify the input within one minute.",
+      () => this.#pending.delete(id)
+    );
+  }
+  async close() {
+    if (this.#exited) return;
+    if (!this.#closing) {
+      this.#closing = true;
+      this.#process.stdin.write(`${JSON.stringify({ type: "close" })}
+`);
+    }
+    try {
+      await withTimeout(this.#exitPromise, 5e3, "Needle did not stop.");
+    } catch {
+      this.#process.kill("SIGTERM");
+      try {
+        await withTimeout(this.#exitPromise, 2e3, "Needle ignored SIGTERM.");
+      } catch {
+        this.#process.kill("SIGKILL");
+        await Promise.race([
+          this.#exitPromise,
+          new Promise((resolve) => setTimeout(resolve, 2e3))
+        ]);
+      }
+    }
+  }
+  #listen() {
+    const lines = createInterface({ input: this.#process.stdout });
+    lines.on("line", (line) => this.#handleLine(line));
+    this.#process.stderr.on("data", (chunk) => {
+      this.#stderr = `${this.#stderr}${chunk.toString()}`.slice(-16384);
+    });
+    this.#process.once("error", (error) => {
+      this.#fail(
+        new NeedleRuntimeError("service_unavailable", "Needle process failed.", error)
+      );
+    });
+    this.#process.once(
+      "exit",
+      (code, signal) => {
+        this.#exited = true;
+        this.#resolveExit();
+        this.#onClose();
+        if (this.#closing && code === 0) {
+          this.#ready = false;
+          return;
+        }
+        const detail = this.#stderr.trim();
+        this.#fail(
+          new NeedleRuntimeError(
+            "service_unavailable",
+            `Needle stopped${code === null ? ` with ${signal ?? "a signal"}` : ` with code ${code}`}${detail ? `: ${detail}` : "."}`
+          )
+        );
+      }
+    );
+  }
+  #handleLine(line) {
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch (error) {
+      this.#fail(
+        new NeedleRuntimeError(
+          "service_unavailable",
+          "Needle returned invalid process data.",
+          error
+        )
+      );
+      return;
+    }
+    if (!isRecord(message)) return;
+    if (message.type === "ready") {
+      if (message.needleVersion !== NEEDLE_VERSION) {
+        this.#fail(
+          new NeedleRuntimeError(
+            "service_unavailable",
+            `Needle ${NEEDLE_VERSION} is required; worker reported ${String(message.needleVersion)}.`
+          )
+        );
+        return;
+      }
+      this.#ready = true;
+      this.#resolveReady();
+      return;
+    }
+    if (message.type === "error" && !this.#ready) {
+      this.#fail(
+        new NeedleRuntimeError(
+          "service_unavailable",
+          `Needle could not start: ${String(message.message ?? "unknown error")}`
+        )
+      );
+      return;
+    }
+    if (typeof message.id !== "number") return;
+    const pending = this.#pending.get(message.id);
+    if (!pending) return;
+    this.#pending.delete(message.id);
+    if (message.ok !== true) {
+      const workerError = isRecord(message.error) ? String(message.error.message ?? "Needle classification failed.") : "Needle classification failed.";
+      pending.reject(
+        new NeedleRuntimeError("classification_failed", workerError)
+      );
+      return;
+    }
+    try {
+      pending.resolve(validateNeedleResult(message.result, this.#resultConfig));
+    } catch (error) {
+      pending.reject(
+        new NeedleRuntimeError(
+          "classification_failed",
+          "Needle returned an invalid classification.",
+          error
+        )
+      );
+    }
+  }
+  #fail(error) {
+    const wasReady = this.#ready;
+    this.#ready = false;
+    if (!wasReady) this.#rejectReady(error);
+    for (const pending of this.#pending.values()) pending.reject(error);
+    this.#pending.clear();
+    if (wasReady && !this.#closing) this.#onBackgroundError(error);
+    if (!this.#exited && !this.#closing) this.#process.kill("SIGTERM");
+  }
+};
+var spawnProcess = (command, args, options) => spawn(command, [...args], {
+  cwd: options.cwd,
+  env: options.env,
+  stdio: ["pipe", "pipe", "pipe"]
+});
+var runCommand = (command, args, options) => new Promise((resolve, reject) => {
+  const child = spawn(command, [...args], {
+    cwd: options?.cwd,
+    env: options?.env,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  let stdout = "";
+  let stderr = "";
+  let timedOut = false;
+  let settled = false;
+  let forceKill;
+  let rejectAfterKill;
+  const timeout = options?.timeoutMs === void 0 ? void 0 : setTimeout(() => {
+    timedOut = true;
+    child.kill("SIGTERM");
+    forceKill = setTimeout(() => {
+      child.kill("SIGKILL");
+      rejectAfterKill = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        clearTimers();
+        reject(new Error(`${command} exceeded its time limit.`));
+      }, 2e3);
+      rejectAfterKill.unref();
+    }, 2e3);
+    forceKill.unref();
+  }, options.timeoutMs);
+  timeout?.unref();
+  const clearTimers = () => {
+    if (timeout !== void 0) clearTimeout(timeout);
+    if (forceKill !== void 0) clearTimeout(forceKill);
+    if (rejectAfterKill !== void 0) clearTimeout(rejectAfterKill);
+  };
+  child.stdout.on("data", (chunk) => {
+    stdout = `${stdout}${chunk.toString()}`.slice(-262144);
+  });
+  child.stderr.on("data", (chunk) => {
+    stderr = `${stderr}${chunk.toString()}`.slice(-262144);
+  });
+  child.once("error", (error) => {
+    if (settled) return;
+    settled = true;
+    clearTimers();
+    reject(error);
+  });
+  child.once("exit", (code, signal) => {
+    if (settled) return;
+    settled = true;
+    clearTimers();
+    if (timedOut) {
+      reject(new Error(`${command} exceeded its time limit.`));
+      return;
+    }
+    if (code === 0) {
+      resolve({ stdout, stderr });
+      return;
+    }
+    reject(
+      new Error(
+        `${command} failed${code === null ? ` with ${signal ?? "a signal"}` : ` with code ${code}`}${stderr.trim() ? `: ${stderr.trim()}` : "."}`
+      )
+    );
+  });
+});
+function classifierKey(name) {
+  const readable = name.normalize("NFKD").replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "classifier";
+  const hash = createHash("sha256").update(name).digest("hex").slice(0, 12);
+  return `${readable}-${hash}`;
+}
+function pythonIn(environmentDirectory) {
+  return process.platform === "win32" ? join(environmentDirectory, "Scripts", "python.exe") : join(environmentDirectory, "bin", "python");
+}
+async function exists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readJson(path) {
+  try {
+    const value = JSON.parse(await readFile(path, "utf8"));
+    return isRecord(value) ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function uvAsset() {
+  const key = `${process.platform}-${process.arch}`;
+  const assets = {
+    "darwin-arm64": "uv-aarch64-apple-darwin.tar.gz",
+    "darwin-x64": "uv-x86_64-apple-darwin.tar.gz",
+    "linux-arm64": "uv-aarch64-unknown-linux-gnu.tar.gz",
+    "linux-x64": "uv-x86_64-unknown-linux-gnu.tar.gz",
+    "win32-arm64": "uv-aarch64-pc-windows-msvc.zip",
+    "win32-x64": "uv-x86_64-pc-windows-msvc.zip"
+  };
+  const asset = assets[key];
+  if (!asset) throw new Error(`SwapAI does not support uv on ${key}.`);
+  return asset;
+}
+function checksumFor(asset, sums) {
+  for (const line of sums.split("\n")) {
+    const [hash, file] = line.trim().split(/\s+\*?/);
+    if (file === asset && /^[a-f0-9]{64}$/i.test(hash ?? "")) return hash;
+  }
+  throw new Error(`The uv checksum list did not contain ${asset}.`);
+}
+async function findFile(directory, name) {
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+    if (entry.isFile() && entry.name === name) return path;
+    if (entry.isDirectory()) {
+      const nested = await findFile(path, name);
+      if (nested) return nested;
+    }
+  }
+  return void 0;
+}
+function withTimeout(promise, milliseconds, message, onTimeout) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      onTimeout?.();
+      reject(new NeedleRuntimeError("service_unavailable", message));
+    }, milliseconds);
+    timer.unref();
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      }
+    );
+  });
+}
+function toRuntimeError(message, cause) {
+  return cause instanceof NeedleRuntimeError ? cause : new NeedleRuntimeError("service_unavailable", message, cause);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/storage.ts
+import { createHash as createHash2 } from "crypto";
+import { chmodSync, mkdirSync } from "fs";
+import { createRequire } from "module";
+import { join as join2 } from "path";
+var { DatabaseSync } = createRequire(import.meta.url)("node:sqlite");
+var SCHEMA = `
+  CREATE TABLE IF NOT EXISTS classifiers (
+    name TEXT PRIMARY KEY,
+    config_json TEXT NOT NULL,
+    max_training_set INTEGER NOT NULL,
+    active_generation INTEGER NOT NULL DEFAULT 1,
+    total_examples_logged INTEGER NOT NULL DEFAULT 0,
+    new_examples_since_training INTEGER NOT NULL DEFAULT 0,
+    training_attempts INTEGER NOT NULL DEFAULT 0,
+    examples_used_for_training INTEGER NOT NULL DEFAULT 0,
+    local_classifications_since_retest INTEGER NOT NULL DEFAULT 0,
+    total_local_classifications INTEGER NOT NULL DEFAULT 0,
+    total_retests INTEGER NOT NULL DEFAULT 0,
+    consecutive_retest_failures INTEGER NOT NULL DEFAULT 0,
+    training_lease_owner TEXT,
+    training_lease_until INTEGER,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS generations (
+    classifier_name TEXT NOT NULL,
+    generation INTEGER NOT NULL,
+    status TEXT NOT NULL CHECK (status IN ('active', 'archived')),
+    trained INTEGER NOT NULL DEFAULT 0,
+    model_path TEXT,
+    needle_version TEXT,
+    created_at INTEGER NOT NULL,
+    archived_at INTEGER,
+    PRIMARY KEY (classifier_name, generation),
+    FOREIGN KEY (classifier_name) REFERENCES classifiers(name) ON DELETE CASCADE
+  );
+
+  CREATE TABLE IF NOT EXISTS examples (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    classifier_name TEXT NOT NULL,
+    generation INTEGER NOT NULL,
+    input TEXT NOT NULL,
+    result_json TEXT NOT NULL,
+    split TEXT NOT NULL CHECK (split IN ('training', 'held_out')),
+    created_at INTEGER NOT NULL,
+    FOREIGN KEY (classifier_name, generation)
+      REFERENCES generations(classifier_name, generation) ON DELETE CASCADE
+  );
+
+  CREATE INDEX IF NOT EXISTS examples_by_generation
+    ON examples(classifier_name, generation, id);
+  CREATE INDEX IF NOT EXISTS examples_by_split
+    ON examples(classifier_name, generation, split, id);
+`;
+function assignExampleSplit(name, input) {
+  const hash = createHash2("sha256").update(name).update("\0").update(input).digest();
+  return hash.readUInt32BE(0) % 10 < 8 ? "training" : "held_out";
+}
+function openStorage(options) {
+  if (!Number.isSafeInteger(options.maxTrainingSet) || options.maxTrainingSet <= 0) {
+    throw new TypeError("maxTrainingSet must be a positive integer");
+  }
+  mkdirSync(options.dataDirectory, { recursive: true, mode: 448 });
+  chmodSync(options.dataDirectory, 448);
+  const databasePath = join2(options.dataDirectory, "swapai.sqlite");
+  const database = new DatabaseSync(databasePath);
+  chmodSync(databasePath, 384);
+  database.exec("PRAGMA journal_mode = WAL");
+  database.exec("PRAGMA foreign_keys = ON");
+  database.exec("PRAGMA busy_timeout = 5000");
+  database.exec(SCHEMA);
+  const now = Date.now();
+  const configJson = stringifyJson(options.config, "classifier config");
+  const existing = database.prepare(`
+    SELECT config_json FROM classifiers WHERE name = ?
+  `).get(options.name);
+  if (existing !== void 0 && criticalConfigJson(existing.config_json) !== criticalConfigJson(configJson)) {
+    database.close();
+    throw new TypeError(
+      `Classifier "${options.name}" already exists with different result or behavior settings`
+    );
+  }
+  transaction(database, () => {
+    database.prepare(`
+      INSERT INTO classifiers (
+        name, config_json, max_training_set, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(name) DO UPDATE SET
+        config_json = excluded.config_json,
+        max_training_set = excluded.max_training_set,
+        updated_at = excluded.updated_at
+    `).run(options.name, configJson, options.maxTrainingSet, now, now);
+    database.prepare(`
+      INSERT OR IGNORE INTO generations (
+        classifier_name, generation, status, created_at
+      ) VALUES (?, 1, 'active', ?)
+    `).run(options.name, now);
+    trimExamples(database, options.name, activeGeneration(database, options.name), options.maxTrainingSet);
+  });
+  let closed = false;
+  const storage = {
+    databasePath,
+    snapshot() {
+      assertOpen(closed);
+      const row2 = requiredRow(database.prepare(`
+        SELECT
+          c.name,
+          c.config_json,
+          c.active_generation,
+          c.total_examples_logged,
+          c.new_examples_since_training,
+          c.training_attempts,
+          c.examples_used_for_training,
+          c.local_classifications_since_retest,
+          c.total_local_classifications,
+          c.total_retests,
+          c.consecutive_retest_failures,
+          g.trained,
+          g.model_path,
+          g.needle_version,
+          (
+            SELECT COUNT(*)
+            FROM examples e
+            WHERE e.classifier_name = c.name
+              AND e.generation = c.active_generation
+          ) AS active_example_count
+        FROM classifiers c
+        JOIN generations g
+          ON g.classifier_name = c.name
+          AND g.generation = c.active_generation
+        WHERE c.name = ?
+      `).get(options.name));
+      return {
+        name: row2.name,
+        config: JSON.parse(row2.config_json),
+        activeGeneration: row2.active_generation,
+        activeExampleCount: row2.active_example_count,
+        totalExamplesLogged: row2.total_examples_logged,
+        newExamplesSinceTraining: row2.new_examples_since_training,
+        trainingAttempts: row2.training_attempts,
+        examplesUsedForTraining: row2.examples_used_for_training,
+        localClassificationsSinceRetest: row2.local_classifications_since_retest,
+        totalLocalClassifications: row2.total_local_classifications,
+        totalRetests: row2.total_retests,
+        consecutiveRetestFailures: row2.consecutive_retest_failures,
+        trained: row2.trained === 1,
+        modelPath: row2.model_path,
+        needleVersion: row2.needle_version
+      };
+    },
+    addExample(input, result) {
+      assertOpen(closed);
+      const generation = activeGeneration(database, options.name);
+      const split = assignExampleSplit(options.name, input);
+      const createdAt = Date.now();
+      const resultJson = stringifyJson(result, "classification result");
+      let id = 0;
+      transaction(database, () => {
+        const insertion = database.prepare(`
+          INSERT INTO examples (
+            classifier_name, generation, input, result_json, split, created_at
+          ) VALUES (?, ?, ?, ?, ?, ?)
+        `).run(options.name, generation, input, resultJson, split, createdAt);
+        id = Number(insertion.lastInsertRowid);
+        database.prepare(`
+          UPDATE classifiers
+          SET total_examples_logged = total_examples_logged + 1,
+              new_examples_since_training = new_examples_since_training + 1,
+              updated_at = ?
+          WHERE name = ?
+        `).run(createdAt, options.name);
+        trimExamples(database, options.name, generation, options.maxTrainingSet);
+      });
+      return { id, generation, input, result, split, createdAt };
+    },
+    listExamples(split, generation) {
+      assertOpen(closed);
+      const selectedGeneration = generation ?? activeGeneration(database, options.name);
+      const rows = split === void 0 ? database.prepare(`
+            SELECT id, generation, input, result_json, split, created_at
+            FROM examples
+            WHERE classifier_name = ? AND generation = ?
+            ORDER BY id
+          `).all(options.name, selectedGeneration) : database.prepare(`
+            SELECT id, generation, input, result_json, split, created_at
+            FROM examples
+            WHERE classifier_name = ? AND generation = ? AND split = ?
+            ORDER BY id
+          `).all(options.name, selectedGeneration, split);
+      return rows.map((value) => mapExample(row(value)));
+    },
+    markTrainingAttempted(exampleCount) {
+      assertOpen(closed);
+      if (!Number.isSafeInteger(exampleCount) || exampleCount <= 0) {
+        throw new TypeError("training example count must be a positive integer");
+      }
+      database.prepare(`
+        UPDATE classifiers
+        SET new_examples_since_training = 0,
+            training_attempts = training_attempts + 1,
+            examples_used_for_training = ?,
+            updated_at = ?
+        WHERE name = ?
+      `).run(exampleCount, Date.now(), options.name);
+    },
+    promoteGeneration(model) {
+      assertOpen(closed);
+      const generation = activeGeneration(database, options.name);
+      database.prepare(`
+        UPDATE generations
+        SET trained = 1, model_path = ?, needle_version = ?
+        WHERE classifier_name = ? AND generation = ?
+      `).run(model.modelPath, model.needleVersion, options.name, generation);
+      return generationByNumber(database, options.name, generation);
+    },
+    recordLocalClassification() {
+      assertOpen(closed);
+      database.prepare(`
+        UPDATE classifiers
+        SET local_classifications_since_retest = local_classifications_since_retest + 1,
+            total_local_classifications = total_local_classifications + 1,
+            updated_at = ?
+        WHERE name = ?
+      `).run(Date.now(), options.name);
+      return storage.snapshot().localClassificationsSinceRetest;
+    },
+    recordRetest(passed) {
+      assertOpen(closed);
+      database.prepare(`
+        UPDATE classifiers
+        SET local_classifications_since_retest = 0,
+            total_retests = total_retests + 1,
+            consecutive_retest_failures = CASE
+              WHEN ? = 1 THEN 0
+              ELSE consecutive_retest_failures + 1
+            END,
+            updated_at = ?
+        WHERE name = ?
+      `).run(passed ? 1 : 0, Date.now(), options.name);
+      return storage.snapshot().consecutiveRetestFailures;
+    },
+    claimTrainingLease(owner, durationMs) {
+      assertOpen(closed);
+      if (owner.trim() === "" || !Number.isSafeInteger(durationMs) || durationMs <= 0) {
+        throw new TypeError("training lease needs an owner and positive duration");
+      }
+      const now2 = Date.now();
+      const result = database.prepare(`
+        UPDATE classifiers
+        SET training_lease_owner = ?,
+            training_lease_until = ?,
+            updated_at = ?
+        WHERE name = ?
+          AND (
+            training_lease_owner IS NULL
+            OR training_lease_until <= ?
+            OR training_lease_owner = ?
+          )
+      `).run(owner, now2 + durationMs, now2, options.name, now2, owner);
+      return result.changes === 1;
+    },
+    releaseTrainingLease(owner) {
+      assertOpen(closed);
+      database.prepare(`
+        UPDATE classifiers
+        SET training_lease_owner = NULL,
+            training_lease_until = NULL,
+            updated_at = ?
+        WHERE name = ? AND training_lease_owner = ?
+      `).run(Date.now(), options.name, owner);
+    },
+    archiveAndReset() {
+      assertOpen(closed);
+      let nextGeneration = 0;
+      const changedAt = Date.now();
+      transaction(database, () => {
+        const currentGeneration = activeGeneration(database, options.name);
+        database.prepare(`
+          UPDATE generations
+          SET status = 'archived', archived_at = ?
+          WHERE classifier_name = ? AND generation = ?
+        `).run(changedAt, options.name, currentGeneration);
+        const maximum = requiredRow(database.prepare(`
+          SELECT MAX(generation) AS maximum
+          FROM generations
+          WHERE classifier_name = ?
+        `).get(options.name));
+        nextGeneration = maximum.maximum + 1;
+        database.prepare(`
+          INSERT INTO generations (
+            classifier_name, generation, status, created_at
+          ) VALUES (?, ?, 'active', ?)
+        `).run(options.name, nextGeneration, changedAt);
+        database.prepare(`
+          UPDATE classifiers
+          SET active_generation = ?,
+              new_examples_since_training = 0,
+              training_attempts = 0,
+              examples_used_for_training = 0,
+              training_lease_owner = NULL,
+              training_lease_until = NULL,
+              local_classifications_since_retest = 0,
+              consecutive_retest_failures = 0,
+              updated_at = ?
+          WHERE name = ?
+        `).run(nextGeneration, changedAt, options.name);
+      });
+      return generationByNumber(database, options.name, nextGeneration);
+    },
+    listGenerations() {
+      assertOpen(closed);
+      return database.prepare(`
+        SELECT
+          generation, status, trained, model_path, needle_version,
+          created_at, archived_at
+        FROM generations
+        WHERE classifier_name = ?
+        ORDER BY generation
+      `).all(options.name).map((value) => mapGeneration(row(value)));
+    },
+    close() {
+      if (closed) {
+        return;
+      }
+      closed = true;
+      database.close();
+    }
+  };
+  return storage;
+}
+function activeGeneration(database, name) {
+  const active = requiredRow(database.prepare(`
+    SELECT active_generation FROM classifiers WHERE name = ?
+  `).get(name));
+  return active.active_generation;
+}
+function generationByNumber(database, name, generation) {
+  const stored = requiredRow(database.prepare(`
+    SELECT
+      generation, status, trained, model_path, needle_version,
+      created_at, archived_at
+    FROM generations
+    WHERE classifier_name = ? AND generation = ?
+  `).get(name, generation));
+  return mapGeneration(stored);
+}
+function trimExamples(database, name, generation, maxTrainingSet) {
+  database.prepare(`
+    DELETE FROM examples
+    WHERE classifier_name = ?
+      AND generation = ?
+      AND id NOT IN (
+        SELECT id
+        FROM examples
+        WHERE classifier_name = ? AND generation = ?
+        ORDER BY id DESC
+        LIMIT ?
+      )
+  `).run(name, generation, name, generation, maxTrainingSet);
+}
+function mapExample(stored) {
+  return {
+    id: stored.id,
+    generation: stored.generation,
+    input: stored.input,
+    result: JSON.parse(stored.result_json),
+    split: stored.split,
+    createdAt: stored.created_at
+  };
+}
+function mapGeneration(stored) {
+  return {
+    generation: stored.generation,
+    status: stored.status,
+    trained: stored.trained === 1,
+    modelPath: stored.model_path,
+    needleVersion: stored.needle_version,
+    createdAt: stored.created_at,
+    archivedAt: stored.archived_at
+  };
+}
+function transaction(database, action) {
+  database.exec("BEGIN IMMEDIATE");
+  try {
+    action();
+    database.exec("COMMIT");
+  } catch (error) {
+    database.exec("ROLLBACK");
+    throw error;
+  }
+}
+function stringifyJson(value, description) {
+  const serialized = JSON.stringify(value);
+  if (serialized === void 0) {
+    throw new TypeError(`${description} must be JSON serializable`);
+  }
+  return serialized;
+}
+function criticalConfigJson(configJson) {
+  const config = JSON.parse(configJson);
+  if (!isRecord2(config)) {
+    throw new TypeError("classifier config must be an object");
+  }
+  const critical = {};
+  for (const key of [
+    "result",
+    "retrainOnCount",
+    "acceptableError",
+    "retestInterval",
+    "retestRevertOn",
+    "model"
+  ]) {
+    if (Object.hasOwn(config, key)) {
+      critical[key] = config[key];
+    }
+  }
+  if (typeof critical.acceptableError === "string") {
+    const percentage = /^(\d+(?:\.\d+)?)%$/.exec(critical.acceptableError);
+    if (percentage !== null) {
+      critical.acceptableError = Number(percentage[1]) / 100;
+    }
+  }
+  if (isRecord2(critical.result) && Array.isArray(critical.result.values)) {
+    critical.result = {
+      ...critical.result,
+      values: [...critical.result.values].sort(compareJsonValues)
+    };
+  }
+  return JSON.stringify(sortObjectKeys(critical));
+}
+function sortObjectKeys(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortObjectKeys);
+  }
+  if (!isRecord2(value)) {
+    return value;
+  }
+  return Object.fromEntries(
+    Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, child]) => [key, sortObjectKeys(child)])
+  );
+}
+function compareJsonValues(left, right) {
+  return JSON.stringify(sortObjectKeys(left)).localeCompare(
+    JSON.stringify(sortObjectKeys(right))
+  );
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertOpen(closed) {
+  if (closed) {
+    throw new Error("Storage is closed");
+  }
+}
+function row(value) {
+  return value;
+}
+function requiredRow(value) {
+  if (value === void 0) {
+    throw new Error("Expected stored classifier data");
+  }
+  return row(value);
+}
+
+// src/classifier.ts
+var TRAINING_LEASE_DURATION_MS = 5 * 60 * 1e3;
+var TRAINING_LEASE_RENEWAL_MS = 60 * 1e3;
+function init(inputConfig) {
+  const config = normalizeConfig(inputConfig);
+  const dataDirectory = config.dataDirectory ?? join3(process.cwd(), ".swapai");
+  const storage = openClassifierStorage(config, dataDirectory);
+  const runtime = createNeedleRuntime({
+    dataDirectory,
+    onBackgroundError: (error) => reportBackgroundError(
+      config,
+      new SwapAIError("service_unavailable", error.message, { cause: error })
+    )
+  });
+  return createClassifier(config, storage, runtime);
+}
+function openClassifierStorage(config, dataDirectory) {
+  try {
+    return openStorage({
+      dataDirectory,
+      name: config.name,
+      maxTrainingSet: config.maxTrainingSet,
+      config: {
+        result: config.result,
+        retrainOnCount: config.retrainOnCount,
+        acceptableError: config.acceptableError,
+        retestInterval: config.retestInterval,
+        retestRevertOn: config.retestRevertOn,
+        model: config.model
+      }
+    });
+  } catch (error) {
+    throw new SwapAIError(
+      error instanceof TypeError ? "invalid_configuration" : "storage_failed",
+      error instanceof Error ? error.message : "Could not open SwapAI storage",
+      { cause: error }
+    );
+  }
+}
+function createClassifier(config, storage, runtime) {
+  let closed = false;
+  let trained = storage.snapshot().trained;
+  let loadedModel = null;
+  let operationQueue = Promise.resolve();
+  let trainingQueue = Promise.resolve();
+  let trainingScheduled = false;
+  const trainingLeaseOwner = `${process.pid}:${randomUUID2()}`;
+  let classificationQueue = Promise.resolve();
+  let queuedFailure = null;
+  const saved = storage.snapshot();
+  if (saved.trained && (saved.modelPath === null || saved.needleVersion !== NEEDLE_VERSION)) {
+    storage.archiveAndReset();
+    trained = false;
+  }
+  const startup = startRuntime();
+  async function startRuntime() {
+    try {
+      await runtime.ready();
+      const snapshot = storage.snapshot();
+      if (snapshot.trained && snapshot.modelPath !== null) {
+        loadedModel = await runtime.loadModel({
+          modelPath: snapshot.modelPath,
+          resultConfig: config.result
+        });
+      }
+    } catch (error) {
+      const swapAIError = toSwapAIError(
+        error,
+        "service_unavailable",
+        "Needle could not start"
+      );
+      rememberBackgroundFailure(swapAIError);
+    }
+  }
+  function rememberBackgroundFailure(error) {
+    queuedFailure = error;
+    reportBackgroundError(config, error);
+  }
+  function enqueue(operation) {
+    const result = operationQueue.then(operation);
+    operationQueue = result.catch((error) => {
+      rememberBackgroundFailure(
+        toSwapAIError(error, "storage_failed", "Background work failed")
+      );
+    });
+    return result;
+  }
+  function persistExample(input, result) {
+    return enqueue(() => {
+      storage.addExample(input, result);
+      scheduleTraining();
+    });
+  }
+  function shouldTrain(snapshot = storage.snapshot()) {
+    return !snapshot.trained && snapshot.examplesUsedForTraining < config.maxTrainingSet && snapshot.newExamplesSinceTraining >= config.retrainOnCount;
+  }
+  function scheduleTraining() {
+    if (trainingScheduled || !shouldTrain()) return;
+    trainingScheduled = true;
+    let completedAttempt = false;
+    const attempt = operationQueue.then(async () => {
+      completedAttempt = await trainWhenDue();
+    });
+    trainingQueue = attempt.catch((error) => {
+      rememberBackgroundFailure(
+        toSwapAIError(error, "service_unavailable", "Needle training failed")
+      );
+    }).finally(() => {
+      trainingScheduled = false;
+      if (completedAttempt) scheduleTraining();
+    });
+  }
+  async function trainWhenDue() {
+    if (!shouldTrain()) return false;
+    if (!storage.claimTrainingLease(trainingLeaseOwner, TRAINING_LEASE_DURATION_MS)) {
+      return false;
+    }
+    let leaseHeld = true;
+    const renewTrainingLease = () => {
+      if (!leaseHeld) return false;
+      try {
+        leaseHeld = storage.claimTrainingLease(
+          trainingLeaseOwner,
+          TRAINING_LEASE_DURATION_MS
+        );
+      } catch {
+        leaseHeld = false;
+      }
+      return leaseHeld;
+    };
+    const leaseRenewal = setInterval(
+      renewTrainingLease,
+      TRAINING_LEASE_RENEWAL_MS
+    );
+    leaseRenewal.unref();
+    try {
+      const snapshot = storage.snapshot();
+      if (!shouldTrain(snapshot)) return false;
+      const trainingExamples = storage.listExamples("training");
+      const heldOutExamples = storage.listExamples("held_out");
+      storage.markTrainingAttempted(snapshot.activeExampleCount);
+      if (trainingExamples.length === 0 || heldOutExamples.length === 0) {
+        return true;
+      }
+      const candidate = await runtime.train({
+        classifierName: config.name,
+        generation: snapshot.activeGeneration,
+        examples: trainingExamples.map(({ input, result }) => ({ input, result })),
+        resultConfig: config.result
+      });
+      const candidateModel = await runtime.loadModel({
+        modelPath: candidate.modelPath,
+        resultConfig: config.result
+      });
+      try {
+        const comparisons = [];
+        for (const example of heldOutExamples) {
+          const candidateResult = validateResult(
+            config.result,
+            await candidateModel.classify(example.input)
+          );
+          comparisons.push({
+            reference: validateResult(config.result, example.result),
+            candidate: candidateResult
+          });
+        }
+        if (averageError(config.result, comparisons) > config.acceptableError) {
+          return true;
+        }
+        if (!renewTrainingLease()) {
+          throw new SwapAIError(
+            "service_unavailable",
+            `Classifier "${config.name}" lost its training lease`
+          );
+        }
+        storage.promoteGeneration(candidate);
+        if (loadedModel !== null) await loadedModel.close();
+        loadedModel = candidateModel;
+        trained = true;
+        return true;
+      } finally {
+        if (loadedModel !== candidateModel) await candidateModel.close();
+      }
+    } finally {
+      clearInterval(leaseRenewal);
+      storage.releaseTrainingLease(trainingLeaseOwner);
+    }
+  }
+  async function model() {
+    await startup;
+    if (!trained) {
+      throw new SwapAIError(
+        "not_trained",
+        `Classifier "${config.name}" has not passed its held-out test`
+      );
+    }
+    if (loadedModel === null) {
+      const snapshot = storage.snapshot();
+      if (snapshot.modelPath === null) {
+        throw new SwapAIError(
+          "service_unavailable",
+          `Classifier "${config.name}" is trained but has no saved model`
+        );
+      }
+      await runtime.ready();
+      loadedModel = await runtime.loadModel({
+        modelPath: snapshot.modelPath,
+        resultConfig: config.result
+      });
+    }
+    return loadedModel;
+  }
+  async function callReference(input, reference) {
+    return validateResult(config.result, await reference(input));
+  }
+  async function fallbackToReference(input, reference, candidateError, retestDue) {
+    if (reference === void 0) {
+      throw toSwapAIError(
+        candidateError,
+        "classification_failed",
+        "Needle classification failed"
+      );
+    }
+    reportBackgroundError(
+      config,
+      toSwapAIError(
+        candidateError,
+        "classification_failed",
+        "Needle classification failed; the reference classifier was used"
+      )
+    );
+    const referenceResult = await callReference(input, reference);
+    await persistExample(input, referenceResult);
+    if (retestDue) {
+      storage.recordLocalClassification();
+      const failures = storage.recordRetest(false);
+      if (failures >= config.retestRevertOn) await disableModel();
+    }
+    return referenceResult;
+  }
+  async function disableModel() {
+    storage.archiveAndReset();
+    trained = false;
+    const previousModel = loadedModel;
+    loadedModel = null;
+    if (previousModel !== null) await previousModel.close();
+  }
+  async function classifyNow(input, reference) {
+    assertOpen2(closed);
+    if (!trained) {
+      if (reference === void 0) {
+        throw new SwapAIError(
+          "not_trained",
+          `Classifier "${config.name}" has not passed its held-out test`
+        );
+      }
+      const referenceResult2 = await callReference(input, reference);
+      await persistExample(input, referenceResult2);
+      return referenceResult2;
+    }
+    const snapshot = storage.snapshot();
+    const retestDue = config.retestInterval > 0 && snapshot.localClassificationsSinceRetest + 1 >= config.retestInterval;
+    let candidateResult;
+    try {
+      candidateResult = validateResult(
+        config.result,
+        await (await model()).classify(input)
+      );
+    } catch (error) {
+      return fallbackToReference(input, reference, error, retestDue);
+    }
+    if (!retestDue || reference === void 0) {
+      storage.recordLocalClassification();
+      return candidateResult;
+    }
+    const referenceResult = await callReference(input, reference);
+    await persistExample(input, referenceResult);
+    storage.recordLocalClassification();
+    const passed = resultError(config.result, referenceResult, candidateResult) <= config.acceptableError;
+    const failures = storage.recordRetest(passed);
+    if (!passed && failures >= config.retestRevertOn) {
+      await disableModel();
+    }
+    return referenceResult;
+  }
+  const classifier = {
+    isTrained() {
+      return trained;
+    },
+    logClassification(input, result) {
+      assertOpen2(closed);
+      const validResult = validateResult(config.result, result);
+      void persistExample(input, validResult);
+    },
+    classify(input, reference) {
+      assertOpen2(closed);
+      const task = classificationQueue.then(() => classifyNow(input, reference));
+      classificationQueue = task.then(
+        () => void 0,
+        () => void 0
+      );
+      return task;
+    },
+    async flush() {
+      await startup;
+      while (true) {
+        const operations = operationQueue;
+        await operations;
+        const training = trainingQueue;
+        await training;
+        if (operations === operationQueue && training === trainingQueue) break;
+      }
+      if (queuedFailure !== null) {
+        const failure = queuedFailure;
+        queuedFailure = null;
+        throw failure;
+      }
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      let failure;
+      try {
+        await classificationQueue;
+        await classifier.flush();
+      } catch (error) {
+        failure = error;
+      } finally {
+        if (loadedModel !== null) await loadedModel.close();
+        loadedModel = null;
+        await runtime.close();
+        storage.close();
+      }
+      if (failure !== void 0) throw failure;
+    }
+  };
+  return classifier;
+}
+function assertOpen2(closed) {
+  if (closed) {
+    throw new SwapAIError("service_unavailable", "Classifier is closed");
+  }
+}
+function toSwapAIError(error, code, message) {
+  if (error instanceof SwapAIError) return error;
+  return new SwapAIError(code, message, { cause: error });
+}
+function reportBackgroundError(config, error) {
+  try {
+    config.onBackgroundError?.(error);
+  } catch {
+  }
+}
+export {
+  SwapAIError,
+  init
+};
+//# sourceMappingURL=index.js.map