interscript 2.4.5 → 3.1.0

package/dist/ml/provision/manifest.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Manifest-driven model resolution.
+ *
+ * The source of truth for "what model version is current" lives in
+ * the `@interscript/models` npm package (a tiny JSON manifest kept
+ * in lockstep with GH Releases in `interscript/ml-models`).
+ *
+ * Resolution order for the manifest itself:
+ *   1. Programmatically injected via `setManifestUrl()` or
+ *      `setInlineManifest()` (tests, air-gapped envs).
+ *   2. The `@interscript/models` package, when installed.
+ *   3. A remote JSON URL on the CDN (`manifest.json` next to the
+ *      release assets).
+ *
+ * See `ml-models/TODO.distribution/04-npm-packages.md` for the
+ * full MECE breakdown of who owns what.
+ */
+/**
+ * Per-task manifest entry. Matches `npm/models/manifest.json` shape.
+ */
+export interface ManifestModelEntry {
+    readonly status: "preview" | "stable" | "deprecated";
+    readonly version: string;
+    readonly note?: string;
+    readonly cdn_base: string;
+    readonly github_base: string;
+}
+export interface Manifest {
+    readonly schema_version: number;
+    readonly models: Readonly<Record<string, ManifestModelEntry>>;
+}
+/**
+ * Asset variants a release may ship. `fp32` (no suffix) is the
+ * default; q8 is the browser-optimized default.
+ */
+export type AssetVariant = "fp32" | "q8" | "q4" | "fp16";
+/**
+ * Serialization format. ONNX is the historical default; LiteRT (.tflite)
+ * is the 2026 alternative backed by Google's LiteRT.js runtime.
+ *
+ * The two formats are orthogonal to `AssetVariant` — both can be
+ * quantized to q8, both can be fp32. The runtime that loads the file
+ * is what differs.
+ */
+export type AssetFormat = "onnx" | "tflite";
+export declare function setInlineManifest(m: Manifest | null): void;
+export declare function setManifestUrl(url: string | null): void;
+/**
+ * Load the manifest. Cached after first call; bust the cache with
+ * `setInlineManifest()` or `setManifestUrl()`.
+ */
+export declare function loadManifest(): Promise<Manifest>;
+/**
+ * Resolve a `(kind, id)` ref to a manifest entry. The `id` field on
+ * a ModelRef carries the task name (e.g. "rababa_arabic"); the kind
+ * is redundant but kept for backwards compatibility.
+ *
+ * Returns `null` if the task isn't in the manifest. Callers decide
+ * whether that's an error or a "use bundled fallback" signal.
+ */
+export declare function resolveManifestEntry(kind: string, id: string): Promise<ManifestModelEntry | null>;
+/**
+ * Build concrete artifact URLs for a model. Prefers the CDN base;
+ * GitHub Releases base is the fallback (slower, but no CDN cache).
+ *
+ * Both URLs use the same asset naming convention so a downloader
+ * can verify checksums identically against either source.
+ */
+export declare function artifactUrls(entry: ManifestModelEntry, variant?: AssetVariant, format?: AssetFormat): {
+    primary: string;
+    fallback: string;
+    assetName: string;
+};
+/**
+ * Sidecar artifacts that ship with every release. These names match
+ * the release pipeline in `ml-models/.github/workflows/release.yml`.
+ */
+export declare function sidecarFilenames(entry: ManifestModelEntry, variant?: AssetVariant, format?: AssetFormat): readonly string[];
+//# sourceMappingURL=manifest.d.ts.map

package/dist/ml/provision/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/ml/provision/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,YAAY,CAAA;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAA;CAC9D;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,MAAM,CAAA;AAExD;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,CAAA;AAkB3C,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,QAAQ,GAAG,IAAI,GAAG,IAAI,CAG1D;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAGvD;AAWD;;;GAGG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,QAAQ,CAAC,CAetD;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAIpC;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,YAAmB,EAC5B,MAAM,GAAE,WAAoB,GAC3B;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAS1D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,YAAmB,EAC5B,MAAM,GAAE,WAAoB,GAC3B,SAAS,MAAM,EAAE,CAGnB"}

package/dist/ml/provision/manifest.js

@@ -0,0 +1,122 @@
+/**
+ * Manifest-driven model resolution.
+ *
+ * The source of truth for "what model version is current" lives in
+ * the `@interscript/models` npm package (a tiny JSON manifest kept
+ * in lockstep with GH Releases in `interscript/ml-models`).
+ *
+ * Resolution order for the manifest itself:
+ *   1. Programmatically injected via `setManifestUrl()` or
+ *      `setInlineManifest()` (tests, air-gapped envs).
+ *   2. The `@interscript/models` package, when installed.
+ *   3. A remote JSON URL on the CDN (`manifest.json` next to the
+ *      release assets).
+ *
+ * See `ml-models/TODO.distribution/04-npm-packages.md` for the
+ * full MECE breakdown of who owns what.
+ */
+import { getModelBase } from "./base.js";
+const VARIANT_SUFFIX = {
+    fp32: "",
+    q8: "-q8",
+    q4: "-q4",
+    fp16: "-fp16",
+};
+const FORMAT_EXTENSION = {
+    onnx: ".onnx",
+    tflite: ".tflite",
+};
+let cachedManifest = null;
+let inlineManifest = null;
+let manifestUrlOverride = null;
+export function setInlineManifest(m) {
+    inlineManifest = m;
+    cachedManifest = null;
+}
+export function setManifestUrl(url) {
+    manifestUrlOverride = url;
+    cachedManifest = null;
+}
+/**
+ * Default manifest URL — sits next to release assets on the CDN.
+ * Points at the jsDelivr mirror of the ml-models repo so it works
+ * with zero npm install.
+ */
+function defaultManifestUrl() {
+    return `${getModelBase()}/npm/models/manifest.json`;
+}
+/**
+ * Load the manifest. Cached after first call; bust the cache with
+ * `setInlineManifest()` or `setManifestUrl()`.
+ */
+export async function loadManifest() {
+    if (cachedManifest)
+        return cachedManifest;
+    if (inlineManifest) {
+        cachedManifest = inlineManifest;
+        return cachedManifest;
+    }
+    const url = manifestUrlOverride ?? defaultManifestUrl();
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`Failed to load model manifest from ${url}: ${res.status} ${res.statusText}`);
+    }
+    const json = (await res.json());
+    cachedManifest = json;
+    return json;
+}
+/**
+ * Resolve a `(kind, id)` ref to a manifest entry. The `id` field on
+ * a ModelRef carries the task name (e.g. "rababa_arabic"); the kind
+ * is redundant but kept for backwards compatibility.
+ *
+ * Returns `null` if the task isn't in the manifest. Callers decide
+ * whether that's an error or a "use bundled fallback" signal.
+ */
+export async function resolveManifestEntry(kind, id) {
+    const manifest = await loadManifest();
+    const taskKey = id.startsWith(`${kind}_`) ? id : `${kind}_${id}`;
+    return manifest.models[taskKey] ?? manifest.models[id] ?? null;
+}
+/**
+ * Build concrete artifact URLs for a model. Prefers the CDN base;
+ * GitHub Releases base is the fallback (slower, but no CDN cache).
+ *
+ * Both URLs use the same asset naming convention so a downloader
+ * can verify checksums identically against either source.
+ */
+export function artifactUrls(entry, variant = "q8", format = "onnx") {
+    const assetName = assetNameFor(entry, variant, format);
+    const versionedCdn = entry.cdn_base.replace("{version}", entry.version);
+    const versionedGithub = entry.github_base.replace("{version}", entry.version);
+    return {
+        primary: `${versionedCdn}${assetName}`,
+        fallback: `${versionedGithub}${assetName}`,
+        assetName,
+    };
+}
+/**
+ * Sidecar artifacts that ship with every release. These names match
+ * the release pipeline in `ml-models/.github/workflows/release.yml`.
+ */
+export function sidecarFilenames(entry, variant = "q8", format = "onnx") {
+    const asset = assetNameFor(entry, variant, format);
+    return [`${asset}.sha256`, "vocab.json", "config.json"];
+}
+function assetNameFor(entry, variant, format = "onnx") {
+    const task = taskNameFromBases(entry);
+    return `${task}${VARIANT_SUFFIX[variant]}${FORMAT_EXTENSION[format]}`;
+}
+/**
+ * Best-effort task name extraction from `cdn_base`/`github_base`.
+ * Both bases end with `<task>-v{version}/`, so we slice off the
+ * trailing version segment.
+ */
+function taskNameFromBases(entry) {
+    const lastSegment = entry.github_base.split("/").filter(Boolean).pop() ?? "";
+    const suffix = "-v{version}";
+    if (lastSegment.endsWith(suffix))
+        return lastSegment.slice(0, -suffix.length);
+    throw new Error(`Cannot extract task name from manifest entry. github_base=${entry.github_base}`);
+}
+//# sourceMappingURL=manifest.js.map

package/dist/ml/provision/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../../src/ml/provision/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAkCxC,MAAM,cAAc,GAAiC;IACnD,IAAI,EAAE,EAAE;IACR,EAAE,EAAE,KAAK;IACT,EAAE,EAAE,KAAK;IACT,IAAI,EAAE,OAAO;CACd,CAAA;AAED,MAAM,gBAAgB,GAAgC;IACpD,IAAI,EAAE,OAAO;IACb,MAAM,EAAE,SAAS;CAClB,CAAA;AAED,IAAI,cAAc,GAAoB,IAAI,CAAA;AAC1C,IAAI,cAAc,GAAoB,IAAI,CAAA;AAC1C,IAAI,mBAAmB,GAAkB,IAAI,CAAA;AAE7C,MAAM,UAAU,iBAAiB,CAAC,CAAkB;IAClD,cAAc,GAAG,CAAC,CAAA;IAClB,cAAc,GAAG,IAAI,CAAA;AACvB,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,GAAkB;IAC/C,mBAAmB,GAAG,GAAG,CAAA;IACzB,cAAc,GAAG,IAAI,CAAA;AACvB,CAAC;AAED;;;;GAIG;AACH,SAAS,kBAAkB;IACzB,OAAO,GAAG,YAAY,EAAE,2BAA2B,CAAA;AACrD,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,IAAI,cAAc;QAAE,OAAO,cAAc,CAAA;IACzC,IAAI,cAAc,EAAE,CAAC;QACnB,cAAc,GAAG,cAAc,CAAA;QAC/B,OAAO,cAAc,CAAA;IACvB,CAAC;IAED,MAAM,GAAG,GAAG,mBAAmB,IAAI,kBAAkB,EAAE,CAAA;IACvD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAA;IAC5B,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,sCAAsC,GAAG,KAAK,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC,CAAA;IAC/F,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAa,CAAA;IAC3C,cAAc,GAAG,IAAI,CAAA;IACrB,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,IAAY,EACZ,EAAU;IAEV,MAAM,QAAQ,GAAG,MAAM,YAAY,EAAE,CAAA;IACrC,MAAM,OAAO,GAAG,EAAE,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,EAAE,EAAE,CAAA;IAChE,OAAO,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,IAAI,CAAA;AAChE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAyB,EACzB,UAAwB,IAAI,EAC5B,SAAsB,MAAM;IAE5B,MAAM,SAAS,GAAG,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,CAAA;IACtD,MAAM,YAAY,GAAG,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IACvE,MAAM,eAAe,GAAG,KAAK,CAAC,WAAW,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IAC7E,OAAO;QACL,OAAO,EAAE,GAAG,YAAY,GAAG,SAAS,EAAE;QACtC,QAAQ,EAAE,GAAG,eAAe,GAAG,SAAS,EAAE;QAC1C,SAAS;KACV,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAyB,EACzB,UAAwB,IAAI,EAC5B,SAAsB,MAAM;IAE5B,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,CAAA;IAClD,OAAO,CAAC,GAAG,KAAK,SAAS,EAAE,YAAY,EAAE,aAAa,CAAC,CAAA;AACzD,CAAC;AAED,SAAS,YAAY,CACnB,KAAyB,EACzB,OAAqB,EACrB,SAAsB,MAAM;IAE5B,MAAM,IAAI,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAA;IACrC,OAAO,GAAG,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,GAAG,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAA;AACvE,CAAC;AAED;;;;GAIG;AACH,SAAS,iBAAiB,CAAC,KAAyB;IAClD,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAA;IAC5E,MAAM,MAAM,GAAG,aAAa,CAAA;IAC5B,IAAI,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAC7E,MAAM,IAAI,KAAK,CAAC,6DAA6D,KAAK,CAAC,WAAW,EAAE,CAAC,CAAA;AACnG,CAAC"}

package/dist/ml/registry.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Model registry — adding a new ML model kind is purely additive.
+ *
+ * Adding ByT5 / Mamba / etc. later = new file in `src/ml/models/<name>/`
+ * that calls `registerModel`. Existing code never changes.
+ *
+ * MECE: every model kind lives in exactly one factory function.
+ * OCP: registry is open for extension, closed for modification.
+ * DRY: shared infrastructure (session creation, provisioning) is
+ *   reused by every model.
+ */
+import type { MLModel, ModelFactory, ModelKind, ModelRef } from "./types.js";
+/**
+ * Register a factory for a model kind. Call once per kind at module
+ * load time.
+ */
+export declare function registerModel(kind: ModelKind, factory: ModelFactory): void;
+/**
+ * Load (or return cached) model for a given ref. The factory is
+ * dispatched by `kind`; the session and artifacts are provisioned
+ * by the provisioner.
+ *
+ * Lazy: models load only when first requested. Subsequent calls
+ * return the cached instance.
+ */
+export declare function loadModel(ref: ModelRef): Promise<MLModel>;
+/**
+ * List registered model kinds (useful for diagnostics).
+ */
+export declare function registeredKinds(): readonly ModelKind[];
+/**
+ * Free all cached models. Used in tests.
+ */
+export declare function resetModels(): Promise<void>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/ml/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/ml/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAK5E;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI,CAK1E;AAQD;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAqB/D;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,SAAS,SAAS,EAAE,CAEtD;AAED;;GAEG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAajD"}

package/dist/ml/registry.js

@@ -0,0 +1,76 @@
+/**
+ * Model registry — adding a new ML model kind is purely additive.
+ *
+ * Adding ByT5 / Mamba / etc. later = new file in `src/ml/models/<name>/`
+ * that calls `registerModel`. Existing code never changes.
+ *
+ * MECE: every model kind lives in exactly one factory function.
+ * OCP: registry is open for extension, closed for modification.
+ * DRY: shared infrastructure (session creation, provisioning) is
+ *   reused by every model.
+ */
+import { provisionModel } from "./provision/index.js";
+const factories = new Map();
+/**
+ * Register a factory for a model kind. Call once per kind at module
+ * load time.
+ */
+export function registerModel(kind, factory) {
+    if (factories.has(kind)) {
+        throw new Error(`Model kind "${kind}" is already registered`);
+    }
+    factories.set(kind, factory);
+}
+const cache = new Map();
+function cacheKey(ref) {
+    return `${ref.kind}/${ref.id}/${ref.url ?? "_default"}`;
+}
+/**
+ * Load (or return cached) model for a given ref. The factory is
+ * dispatched by `kind`; the session and artifacts are provisioned
+ * by the provisioner.
+ *
+ * Lazy: models load only when first requested. Subsequent calls
+ * return the cached instance.
+ */
+export async function loadModel(ref) {
+    const key = cacheKey(ref);
+    const cached = cache.get(key);
+    if (cached)
+        return cached;
+    const factory = factories.get(ref.kind);
+    if (!factory) {
+        throw new Error(`Unknown model kind: "${ref.kind}". Register a factory via registerModel("${ref.kind}", factory).`);
+    }
+    const promise = (async () => {
+        const { session, artifacts } = await provisionModel(ref);
+        return factory({ session, artifacts });
+    })();
+    cache.set(key, promise);
+    // On failure, drop the cached rejection so callers can retry.
+    promise.catch(() => cache.delete(key));
+    return promise;
+}
+/**
+ * List registered model kinds (useful for diagnostics).
+ */
+export function registeredKinds() {
+    return [...factories.keys()];
+}
+/**
+ * Free all cached models. Used in tests.
+ */
+export async function resetModels() {
+    const pending = [...cache.values()];
+    cache.clear();
+    await Promise.allSettled(pending.map(async (p) => {
+        try {
+            const m = await p;
+            await m.dispose();
+        }
+        catch {
+            // already rejected; ignore
+        }
+    }));
+}
+//# sourceMappingURL=registry.js.map

package/dist/ml/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/ml/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAErD,MAAM,SAAS,GAAG,IAAI,GAAG,EAA2B,CAAA;AAEpD;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,IAAe,EAAE,OAAqB;IAClE,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,eAAe,IAAI,yBAAyB,CAAC,CAAA;IAC/D,CAAC;IACD,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;AAC9B,CAAC;AAED,MAAM,KAAK,GAAG,IAAI,GAAG,EAA4B,CAAA;AAEjD,SAAS,QAAQ,CAAC,GAAa;IAC7B,OAAO,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,GAAG,IAAI,UAAU,EAAE,CAAA;AACzD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAa;IAC3C,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAA;IACzB,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC7B,IAAI,MAAM;QAAE,OAAO,MAAM,CAAA;IAEzB,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IACvC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,wBAAwB,GAAG,CAAC,IAAI,4CAA4C,GAAG,CAAC,IAAI,cAAc,CACnG,CAAA;IACH,CAAC;IAED,MAAM,OAAO,GAAG,CAAC,KAAK,IAAI,EAAE;QAC1B,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,MAAM,cAAc,CAAC,GAAG,CAAC,CAAA;QACxD,OAAO,OAAO,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAA;IACxC,CAAC,CAAC,EAAE,CAAA;IAEJ,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;IACvB,8DAA8D;IAC9D,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;IACtC,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,CAAA;AAC9B,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,MAAM,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAA;IACnC,KAAK,CAAC,KAAK,EAAE,CAAA;IACb,MAAM,OAAO,CAAC,UAAU,CACtB,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QACtB,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,MAAM,CAAC,CAAA;YACjB,MAAM,CAAC,CAAC,OAAO,EAAE,CAAA;QACnB,CAAC;QAAC,MAAM,CAAC;YACP,2BAA2B;QAC7B,CAAC;IACH,CAAC,CAAC,CACH,CAAA;AACH,CAAC"}

package/dist/ml/session/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * InferenceSession — abstract interface for running ML models.
+ *
+ * Three backends implement this:
+ *   - onnx-node: native ONNX Runtime via onnxruntime-node (Node.js only)
+ *   - onnx-web: WASM/WebGPU ONNX Runtime via onnxruntime-web (browser)
+ *   - litert-web: LiteRT.js for .tflite models (browser)
+ *
+ * Adding a new backend = adding a new file here + exporting a factory.
+ * Existing code never changes (OCP).
+ *
+ * Backends are loaded lazily — only the one needed is imported, keeping
+ * the bundle size minimal.
+ */
+import type { InferenceSession, InferenceInputs, InferenceOutputs } from "../types.js";
+export type { InferenceSession, InferenceInputs, InferenceOutputs };
+export type { WebSessionOptions } from "./onnx-web.js";
+export type { LitertSessionOptions } from "./litert-web.js";
+/**
+ * Detect environment. Browser backends work in `window`, Node backends
+ * work in `process.versions.node`. Some environments (Cloudflare
+ * Workers, Deno) might prefer Web.
+ */
+export declare function detectBackend(): "node" | "web" | "unknown";
+/**
+ * Options for `createSession`.
+ */
+export interface SessionOptions {
+    /** Force a specific backend. Auto-detected by default. */
+    backend?: "node" | "web";
+    /**
+     * Which runtime to use. ONNX is the default; "litert" selects
+     * Google's LiteRT.js for .tflite models. The runtime choice must
+     * match the model artifact being loaded (.onnx vs .tflite).
+     */
+    runtime?: "onnx" | "litert";
+    /** ONNX-web only: enable WebGPU with WASM fallback. Default: true. */
+    webgpu?: boolean;
+    /** LiteRT-web only: accelerator preference. Default: "webgpu". */
+    litertAccelerator?: "webgpu" | "webnn" | "wasm";
+    /**
+     * LiteRT-web only: input/output tensor names. ONNX reads these from
+     * the model graph; LiteRT's auto-generated names are not user-facing,
+     * so the caller must supply them.
+     */
+    inputNames?: readonly string[];
+    outputNames?: readonly string[];
+}
+/**
+ * Create an InferenceSession from a model file. Auto-picks the backend.
+ * Backend choice can be overridden via opts.backend; runtime choice
+ * via opts.runtime.
+ */
+export declare function createSession(modelData: ArrayBuffer | Uint8Array, opts?: SessionOptions): Promise<InferenceSession>;
+//# sourceMappingURL=index.d.ts.map

package/dist/ml/session/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ml/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEtF,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,gBAAgB,EAAE,CAAA;AACnE,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACtD,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAE3D;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,GAAG,KAAK,GAAG,SAAS,CAS1D;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IACxB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;IAC3B,sEAAsE;IACtE,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,kEAAkE;IAClE,iBAAiB,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAA;IAC/C;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAChC;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,SAAS,EAAE,WAAW,GAAG,UAAU,EACnC,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,gBAAgB,CAAC,CAoB3B"}

package/dist/ml/session/index.js

@@ -0,0 +1,57 @@
+/**
+ * InferenceSession — abstract interface for running ML models.
+ *
+ * Three backends implement this:
+ *   - onnx-node: native ONNX Runtime via onnxruntime-node (Node.js only)
+ *   - onnx-web: WASM/WebGPU ONNX Runtime via onnxruntime-web (browser)
+ *   - litert-web: LiteRT.js for .tflite models (browser)
+ *
+ * Adding a new backend = adding a new file here + exporting a factory.
+ * Existing code never changes (OCP).
+ *
+ * Backends are loaded lazily — only the one needed is imported, keeping
+ * the bundle size minimal.
+ */
+/**
+ * Detect environment. Browser backends work in `window`, Node backends
+ * work in `process.versions.node`. Some environments (Cloudflare
+ * Workers, Deno) might prefer Web.
+ */
+export function detectBackend() {
+    const g = globalThis;
+    if (g.process?.versions?.node) {
+        return "node";
+    }
+    if (g.self !== undefined) {
+        return "web";
+    }
+    return "unknown";
+}
+/**
+ * Create an InferenceSession from a model file. Auto-picks the backend.
+ * Backend choice can be overridden via opts.backend; runtime choice
+ * via opts.runtime.
+ */
+export async function createSession(modelData, opts = {}) {
+    const runtime = opts.runtime ?? "onnx";
+    // LiteRT runs in the browser only (for now — no Node.js build).
+    if (runtime === "litert") {
+        const litertOpts = {};
+        if (opts.litertAccelerator !== undefined)
+            litertOpts.accelerator = opts.litertAccelerator;
+        if (opts.inputNames !== undefined)
+            litertOpts.inputNames = opts.inputNames;
+        if (opts.outputNames !== undefined)
+            litertOpts.outputNames = opts.outputNames;
+        return (await import("./litert-web.js")).createLitertSession(modelData, litertOpts);
+    }
+    const backend = (opts.backend ?? detectBackend() === "node") ? "node" : "web";
+    if (backend === "node") {
+        return (await import("./onnx-node.js")).createNodeSession(modelData);
+    }
+    // Pass through webgpu only when explicitly set — exactOptionalPropertyTypes
+    // distinguishes missing vs undefined, and we want missing = use default.
+    const webOpts = opts.webgpu === undefined ? {} : { webgpu: opts.webgpu };
+    return (await import("./onnx-web.js")).createWebSession(modelData, webOpts);
+}
+//# sourceMappingURL=index.js.map

package/dist/ml/session/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ml/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAQH;;;;GAIG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,CAAC,GAAG,UAA4E,CAAA;IACtF,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QAC9B,OAAO,MAAM,CAAA;IACf,CAAC;IACD,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,KAAK,CAAA;IACd,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AA2BD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,SAAmC,EACnC,OAAuB,EAAE;IAEzB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,MAAM,CAAA;IAEtC,gEAAgE;IAChE,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;QACzB,MAAM,UAAU,GAA4B,EAAE,CAAA;QAC9C,IAAI,IAAI,CAAC,iBAAiB,KAAK,SAAS;YAAE,UAAU,CAAC,WAAW,GAAG,IAAI,CAAC,iBAAiB,CAAA;QACzF,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS;YAAE,UAAU,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAA;QAC1E,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS;YAAE,UAAU,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAA;QAC7E,OAAO,CAAC,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,mBAAmB,CAAC,SAAS,EAAE,UAAU,CAAC,CAAA;IACrF,CAAC;IAED,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,aAAa,EAAE,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAA;IAC7E,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,OAAO,CAAC,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAA;IACtE,CAAC;IACD,4EAA4E;IAC5E,yEAAyE;IACzE,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAA;IACxE,OAAO,CAAC,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,gBAAgB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;AAC7E,CAAC"}

package/dist/ml/session/litert-web.d.ts

@@ -0,0 +1,50 @@
+/**
+ * LiteRT.js backend — runs .tflite models via Google's runtime.
+ *
+ * Parallel to onnx-web.ts. Same InferenceSession interface. Lazy-loaded
+ * so bundlers exclude it from builds that don't use LiteRT.
+ *
+ * `@litertjs/core` is a peer dep — users install it if they want the
+ * LiteRT runtime. Without it, calling with `runtime: 'litert'` throws
+ * a clear error.
+ *
+ * Note: as of v2.5.2 (released July 9, 2026), the LiteRT.js API is
+ * still settling. This wrapper isolates users from API churn — when
+ * Google ships breaking changes, we absorb them here.
+ *
+ * Known API gaps to verify with real models (deferred until v0.1.0
+ * produces a real .tflite artifact):
+ *   - Multi-input: example shows `model.run(singleTensor)`. We pass an
+ *     array when inputNames.length > 1; will adjust if API differs.
+ *   - Multi-output: result object shape unknown until we have a real
+ *     multi-head .tflite.
+ *   - Int64 inputs: our model has int64 src/lengths. Tensor constructor
+ *     accepts TypedArray; BigInt64Array should work but untested.
+ */
+import type { InferenceSession } from "../types.js";
+export interface LitertSessionOptions {
+    /**
+     * Accelerator preference. Default: 'webgpu' (falls back to 'wasm'
+     * automatically inside LiteRT.js if WebGPU is unavailable).
+     */
+    accelerator?: "webgpu" | "webnn" | "wasm";
+    /**
+     * URL prefix serving the LiteRT.js WASM files. Default: jsdelivr CDN.
+     * Override for self-hosted deployments or offline use.
+     */
+    wasmPath?: string;
+}
+/**
+ * Create a LiteRT.js session from a .tflite model blob.
+ *
+ * Caller supplies input/output names because the .tflite default
+ * signature names are auto-generated (e.g. "args_0"). For our rababa
+ * models, use:
+ *   - single-head: inputNames=["src","lengths"], outputNames=["output"]
+ *   - multi-head:  inputNames=["src","lengths"], outputNames=["niqqud","dagesh","sin"]
+ */
+export declare function createLitertSession(modelData: ArrayBuffer | Uint8Array, opts?: LitertSessionOptions & {
+    inputNames?: readonly string[];
+    outputNames?: readonly string[];
+}): Promise<InferenceSession>;
+//# sourceMappingURL=litert-web.d.ts.map

package/dist/ml/session/litert-web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"litert-web.d.ts","sourceRoot":"","sources":["../../../src/ml/session/litert-web.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAKjB,MAAM,aAAa,CAAA;AAEpB,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,WAAW,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAA;IACzC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AA+CD;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,WAAW,GAAG,UAAU,EACnC,IAAI,GAAE,oBAAoB,GAAG;IAC3B,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3B,GACL,OAAO,CAAC,gBAAgB,CAAC,CAuB3B"}

package/dist/ml/session/litert-web.js

@@ -0,0 +1,146 @@
+/**
+ * LiteRT.js backend — runs .tflite models via Google's runtime.
+ *
+ * Parallel to onnx-web.ts. Same InferenceSession interface. Lazy-loaded
+ * so bundlers exclude it from builds that don't use LiteRT.
+ *
+ * `@litertjs/core` is a peer dep — users install it if they want the
+ * LiteRT runtime. Without it, calling with `runtime: 'litert'` throws
+ * a clear error.
+ *
+ * Note: as of v2.5.2 (released July 9, 2026), the LiteRT.js API is
+ * still settling. This wrapper isolates users from API churn — when
+ * Google ships breaking changes, we absorb them here.
+ *
+ * Known API gaps to verify with real models (deferred until v0.1.0
+ * produces a real .tflite artifact):
+ *   - Multi-input: example shows `model.run(singleTensor)`. We pass an
+ *     array when inputNames.length > 1; will adjust if API differs.
+ *   - Multi-output: result object shape unknown until we have a real
+ *     multi-head .tflite.
+ *   - Int64 inputs: our model has int64 src/lengths. Tensor constructor
+ *     accepts TypedArray; BigInt64Array should work but untested.
+ */
+const DEFAULT_WASM_PATH = "https://cdn.jsdelivr.net/npm/@litertjs/core@2.5.2/wasm/";
+let cached;
+async function loadLitertCore() {
+    if (!cached) {
+        cached = (async () => {
+            try {
+                return (await import("@litertjs/core"));
+            }
+            catch (e) {
+                cached = undefined;
+                throw new Error("@litertjs/core is required for LiteRT inference. Install with: npm install @litertjs/core", { cause: e });
+            }
+        })();
+    }
+    return cached;
+}
+/**
+ * Create a LiteRT.js session from a .tflite model blob.
+ *
+ * Caller supplies input/output names because the .tflite default
+ * signature names are auto-generated (e.g. "args_0"). For our rababa
+ * models, use:
+ *   - single-head: inputNames=["src","lengths"], outputNames=["output"]
+ *   - multi-head:  inputNames=["src","lengths"], outputNames=["niqqud","dagesh","sin"]
+ */
+export async function createLitertSession(modelData, opts = {}) {
+    const accelerator = opts.accelerator ?? "webgpu";
+    const wasmPath = opts.wasmPath ?? DEFAULT_WASM_PATH;
+    const inputNames = opts.inputNames ?? ["src", "lengths"];
+    const outputNames = opts.outputNames ?? ["output"];
+    const core = await loadLitertCore();
+    await core.loadLiteRt(wasmPath, { jspi: accelerator === "webnn" });
+    // LiteRT.js takes a URL; create a blob URL from the bytes.
+    // (In Node 18+, Blob + URL.createObjectURL are available globally.)
+    const blob = new Blob([new Uint8Array(modelData)], { type: "application/octet-stream" });
+    const url = URL.createObjectURL(blob);
+    let model;
+    try {
+        model = await core.loadAndCompile(url, { accelerator });
+    }
+    finally {
+        // Model is compiled; the URL can be revoked. If LiteRT keeps lazy
+        // references to the URL, we'd need to defer this to dispose(). Be
+        // conservative and revoke on dispose instead.
+    }
+    return new LitertInferenceSession(model, core, inputNames, outputNames, url);
+}
+class LitertInferenceSession {
+    inputNames;
+    outputNames;
+    model;
+    core;
+    blobUrl;
+    disposed = false;
+    constructor(model, core, inputNames, outputNames, blobUrl) {
+        this.model = model;
+        this.core = core;
+        this.inputNames = inputNames;
+        this.outputNames = outputNames;
+        this.blobUrl = blobUrl;
+    }
+    async run(inputs) {
+        if (this.disposed)
+            throw new Error("Session disposed");
+        // Convert named inputs to LiteRT Tensors, in inputNames order.
+        const tensors = [];
+        for (const name of this.inputNames) {
+            const t = inputs[name];
+            if (!t)
+                throw new Error(`Missing LiteRT input: ${name}`);
+            tensors.push(new this.core.Tensor(t.data, t.dims));
+        }
+        // Pass single tensor directly; pass array for multi-input. The
+        // LiteRT.js v2.5.2 example shows single-tensor `run()`, but the
+        // underlying signature accepts either form. Empirical verification
+        // pending a real multi-input model.
+        const results = await this.model.run(tensors.length === 1 ? tensors[0] : tensors);
+        const out = {};
+        try {
+            for (let i = 0; i < this.outputNames.length; i++) {
+                const name = this.outputNames[i];
+                const resultTensor = results[i];
+                if (!resultTensor) {
+                    throw new Error(`LiteRT produced no output at index ${i} (expected ${name})`);
+                }
+                // Move to wasm-backed readable buffer; safe regardless of where
+                // the tensor currently lives (webgpu or wasm).
+                const moved = await resultTensor.moveTo("wasm");
+                const data = await moved.toTypedArray();
+                out[name] = {
+                    name,
+                    type: dtypeFromTypedArray(data),
+                    data,
+                    dims: [...resultTensor.dims],
+                };
+                await moved.delete();
+            }
+        }
+        finally {
+            await results.delete();
+        }
+        return out;
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        await this.model.delete();
+        URL.revokeObjectURL(this.blobUrl);
+    }
+}
+function dtypeFromTypedArray(arr) {
+    if (arr instanceof Float32Array)
+        return "float32";
+    if (arr instanceof Int32Array)
+        return "int32";
+    if (arr instanceof BigInt64Array)
+        return "int64";
+    if (arr instanceof Uint8Array)
+        return "uint8";
+    return "float32";
+}
+//# sourceMappingURL=litert-web.js.map