@elizaos/shared 2.0.0-beta.1 → 2.0.3-beta.3

package/local-inference/device-fit.js

@@ -0,0 +1,155 @@
+/**
+ * Device-fit selector for the one forced local model (eliza-1).
+ *
+ * The product rule (see `packages/ui/docs/local-model-simplification/README.md`):
+ * **always run the biggest eliza-1 tier we can, balanced against a 128k context
+ * target, with every memory optimization applied** so the floors are as low as
+ * physics allows:
+ *
+ *  - **TurboQuant weights** — the catalog `sizeGb` per tier already reflects the
+ *    TurboQuant-compressed GGUF (e.g. a 2B model is 1.4 GB, not ~4 GB bf16).
+ *  - **Stock q8_0 KV-cache** — Gemma 4's KV is already minimal by construction
+ *    (MQA = 1 KV head, windowed sliding-window attention on most layers, and
+ *    shared-KV layers reusing earlier KV), so a 128k window fits in a fraction
+ *    of a GB at stock q8_0 without the legacy QJL/Polar kernels. The head_dim=128
+ *    QJL kernel does not apply to Gemma's dual head dims (512 global / 256 swa)
+ *    and is not used. KV quant is forced, never a user option.
+ *
+ * `minRamGb` per tier is therefore "TurboQuant weights + a 128k q8_0 KV cache +
+ * runtime/OS overhead". Picking the largest tier whose `minRamGb` fits free RAM
+ * is exactly "biggest model that still gets a 128k window".
+ *
+ * **Dynamic fit-to-RAM context (#8809 M10b).** Picking the largest tier whose
+ * static `minRamGb` floor fits is the coarse gate. On top of that we compute the
+ * *largest context window that actually fits the device's free RAM* for the
+ * chosen tier, from the per-token q8_0 KV rate (`kvBytesPerTokenForTier`) rather
+ * than only honouring the catalog ceiling. On a roomy host that is the tier's
+ * native window; on a host that clears the weights+overhead floor but not a full
+ * 128k cache, the window shrinks to the largest 4k-stepped size that fits. The
+ * tier choice never drops below 2B (0.8B is gone); when even a minimum window
+ * (`ELIZA_1_MIN_LOCAL_CONTEXT`) cannot fit any tier, we return `null`, which the
+ * caller reads as "this modality should route to Cloud" (the AUTO policy).
+ */
+import { MODEL_CATALOG } from "./catalog.js";
+/** The KV-cache quantization eliza-1 always uses on-device. Gemma 4's KV is
+ * already minimal (MQA + windowed-SWA + shared-KV), so stock q8_0 is sufficient;
+ * the legacy head_dim=128 QJL kernel is incompatible with Gemma's dual head dims
+ * (512 global / 256 swa) and is not used. */
+export const ELIZA_1_KV_QUANT = "q8_0";
+/** The consumer context target. We never advertise less than this if it fits. */
+export const ELIZA_1_CONTEXT_TARGET = 131072; // 128k
+/** Floor below which a cramped local window is worse than routing to Cloud. */
+export const ELIZA_1_MIN_LOCAL_CONTEXT = 8192; // 8k
+/** Round a token count down to a 4k step so we advertise clean window sizes. */
+const CONTEXT_STEP = 4096;
+/**
+ * Fixed non-KV cost on top of the TurboQuant weights: the inference runtime,
+ * activation scratch, and OS headroom. Used by the context-fit math to reserve
+ * room before the KV cache claims the rest of free RAM.
+ */
+const RUNTIME_OVERHEAD_GB = 1.0;
+const BYTES_PER_GB = 1024 * 1024 * 1024;
+/**
+ * Per-token q8_0 KV footprint for a tier, derived from the catalog's own
+ * sizing: the tier's `minRamGb` floor is "TurboQuant weights + a native-window
+ * q8_0 KV cache + runtime/OS overhead", so the RAM the catalog reserves for the
+ * KV cache at the native window is `minRamGb − sizeGb − RUNTIME_OVERHEAD_GB`,
+ * and dividing by the native context gives the per-token rate. Deriving it from
+ * the catalog (rather than a second hardcoded table) keeps the full-fit floor
+ * and the dynamic context-downscale math provably consistent: just below a
+ * tier's floor, exactly less-than-native fits.
+ *
+ * Returns `null` when the tier's floor doesn't actually reserve any KV room
+ * (mis-sized catalog row) — the caller then cannot compute a window for it.
+ */
+function kvBytesPerTokenForTier(tier) {
+    const { minRamGb, sizeGb, contextLength } = tier;
+    if (minRamGb == null || sizeGb == null || contextLength == null)
+        return null;
+    const kvReserveGb = minRamGb - sizeGb - RUNTIME_OVERHEAD_GB;
+    if (kvReserveGb <= 0 || contextLength <= 0)
+        return null;
+    return (kvReserveGb * BYTES_PER_GB) / contextLength;
+}
+function roundDownToStep(tokens, step = CONTEXT_STEP) {
+    return Math.max(0, Math.floor(tokens / step) * step);
+}
+/**
+ * Largest 4k-stepped window that fits `freeRamGb` for `tier` at the q8_0 KV
+ * rate. Returns `context: 0` when the weights+overhead alone do not fit, or
+ * when the tier's KV rate cannot be derived (caller treats either as "this
+ * tier cannot hold any window").
+ */
+function maxFittingContextForTier(tier, freeRamGb) {
+    const kvBytesPerToken = kvBytesPerTokenForTier(tier);
+    if (kvBytesPerToken == null)
+        return null;
+    const sizeGb = tier.sizeGb ?? 0;
+    const kvAvailableGb = freeRamGb - sizeGb - RUNTIME_OVERHEAD_GB;
+    if (kvAvailableGb <= 0)
+        return { context: 0, kvBytesPerToken };
+    const tokensThatFit = (kvAvailableGb * BYTES_PER_GB) / kvBytesPerToken;
+    return { context: roundDownToStep(tokensThatFit), kvBytesPerToken };
+}
+/**
+ * Pick the best on-device eliza-1 configuration for a device with `freeRamGb` of
+ * usable RAM (Apple-silicon unified RAM, discrete-GPU VRAM, or CPU RAM — the
+ * caller normalizes this, e.g. via the device-tier classifier).
+ *
+ * Returns `null` when nothing acceptable fits locally → the caller routes this
+ * modality to Cloud (AUTO). Never returns a tier smaller than 2B (0.8B is gone).
+ */
+export function selectBestEliza1Fit(freeRamGb) {
+    if (!Number.isFinite(freeRamGb) || freeRamGb <= 0)
+        return null;
+    // Release tiers, largest RAM-floor first. The floor already bakes in a native
+    // (128k) q8_0 window, so the first one whose floor fits is the biggest model
+    // that still gets its full window.
+    const tiers = [...MODEL_CATALOG]
+        .filter((m) => typeof m.minRamGb === "number" && typeof m.sizeGb === "number")
+        .sort((a, b) => b.minRamGb - a.minRamGb);
+    for (const tier of tiers) {
+        if (tier.minRamGb == null || freeRamGb < tier.minRamGb)
+            continue;
+        const nativeCtx = tier.contextLength ?? ELIZA_1_CONTEXT_TARGET;
+        const fit = maxFittingContextForTier(tier, freeRamGb);
+        if (!fit)
+            continue;
+        const { context: maxFittingContext, kvBytesPerToken } = fit;
+        // Floor fits → at least the native window fits; clamp the dynamic window to
+        // the tier ceiling so we never advertise more than the bundle ships.
+        const contextLength = Math.min(Math.max(maxFittingContext, nativeCtx), nativeCtx);
+        return {
+            tierId: tier.id,
+            contextLength,
+            kvQuant: ELIZA_1_KV_QUANT,
+            contextDownscaled: false,
+            kvBytesPerToken,
+            maxFittingContext,
+            reason: "native-fit",
+        };
+    }
+    // No tier clears its native floor. Keep the smallest tier (2B) and shrink the
+    // q8_0 KV window to the largest 4k step that fits. Never drop below 2B.
+    const smallest = tiers[tiers.length - 1];
+    if (!smallest || smallest.contextLength == null)
+        return null;
+    const nativeCtx = smallest.contextLength;
+    const fit = maxFittingContextForTier(smallest, freeRamGb);
+    if (!fit)
+        return null;
+    const { context: fittedContext, kvBytesPerToken } = fit;
+    if (fittedContext < ELIZA_1_MIN_LOCAL_CONTEXT)
+        return null; // too cramped → Cloud
+    const contextLength = Math.min(fittedContext, nativeCtx);
+    return {
+        tierId: smallest.id,
+        contextLength,
+        kvQuant: ELIZA_1_KV_QUANT,
+        contextDownscaled: contextLength < nativeCtx,
+        kvBytesPerToken,
+        maxFittingContext: fittedContext,
+        reason: contextLength < nativeCtx ? "context-downscaled" : "native-fit",
+    };
+}
+//# sourceMappingURL=device-fit.js.map

package/local-inference/device-fit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-fit.js","sourceRoot":"","sources":["../../src/local-inference/device-fit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG1C;;;6CAG6C;AAC7C,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAe,CAAC;AAEhD,iFAAiF;AACjF,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC,CAAC,OAAO;AAErD,+EAA+E;AAC/E,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,CAAC,CAAC,KAAK;AAEpD,gFAAgF;AAChF,MAAM,YAAY,GAAG,IAAI,CAAC;AAE1B;;;;GAIG;AACH,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAEhC,MAAM,YAAY,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAExC;;;;;;;;;;;;GAYG;AACH,SAAS,sBAAsB,CAAC,IAAkB;IAChD,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC;IACjD,IAAI,QAAQ,IAAI,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,aAAa,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAC7E,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,mBAAmB,CAAC;IAC5D,IAAI,WAAW,IAAI,CAAC,IAAI,aAAa,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACxD,OAAO,CAAC,WAAW,GAAG,YAAY,CAAC,GAAG,aAAa,CAAC;AACtD,CAAC;AAED,SAAS,eAAe,CAAC,MAAc,EAAE,IAAI,GAAG,YAAY;IAC1D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;AACvD,CAAC;AAwBD;;;;;GAKG;AACH,SAAS,wBAAwB,CAC/B,IAAkB,EAClB,SAAiB;IAEjB,MAAM,eAAe,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;IACrD,IAAI,eAAe,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;IAChC,MAAM,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,mBAAmB,CAAC;IAC/D,IAAI,aAAa,IAAI,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,eAAe,EAAE,CAAC;IAC/D,MAAM,aAAa,GAAG,CAAC,aAAa,GAAG,YAAY,CAAC,GAAG,eAAe,CAAC;IACvE,OAAO,EAAE,OAAO,EAAE,eAAe,CAAC,aAAa,CAAC,EAAE,eAAe,EAAE,CAAC;AACtE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAiB;IACnD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAE/D,8EAA8E;IAC9E,6EAA6E;IAC7E,mCAAmC;IACnC,MAAM,KAAK,GAAG,CAAC,GAAG,aAAa,CAAC;SAC7B,MAAM,CACL,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,CACtE;SACA,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;IAE3C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,IAAI,SAAS,GAAG,IAAI,CAAC,QAAQ;YAAE,SAAS;QACjE,MAAM,SAAS,GAAG,IAAI,CAAC,aAAa,IAAI,sBAAsB,CAAC;QAC/D,MAAM,GAAG,GAAG,wBAAwB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACtD,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,MAAM,EAAE,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,GAAG,GAAG,CAAC;QAC5D,4EAA4E;QAC5E,qEAAqE;QACrE,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,CAC5B,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,SAAS,CAAC,EACtC,SAAS,CACV,CAAC;QACF,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,EAAkB;YAC/B,aAAa;YACb,OAAO,EAAE,gBAAgB;YACzB,iBAAiB,EAAE,KAAK;YACxB,eAAe;YACf,iBAAiB;YACjB,MAAM,EAAE,YAAY;SACrB,CAAC;IACJ,CAAC;IAED,8EAA8E;IAC9E,wEAAwE;IACxE,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACzC,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,aAAa,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAC7D,MAAM,SAAS,GAAG,QAAQ,CAAC,aAAa,CAAC;IACzC,MAAM,GAAG,GAAG,wBAAwB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC1D,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,GAAG,GAAG,CAAC;IACxD,IAAI,aAAa,GAAG,yBAAyB;QAAE,OAAO,IAAI,CAAC,CAAC,sBAAsB;IAElF,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IACzD,OAAO;QACL,MAAM,EAAE,QAAQ,CAAC,EAAkB;QACnC,aAAa;QACb,OAAO,EAAE,gBAAgB;QACzB,iBAAiB,EAAE,aAAa,GAAG,SAAS;QAC5C,eAAe;QACf,iBAAiB,EAAE,aAAa;QAChC,MAAM,EAAE,aAAa,GAAG,SAAS,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,YAAY;KACxE,CAAC;AACJ,CAAC"}

package/local-inference/gpu-profiles.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Per-GPU deployment profiles for single-GPU Eliza-1 servers.
+ *
+ * Scope: ONE GPU per host. We do not target NVLink, tensor-parallel splits,
+ * or multi-tenant datacenter workloads. The product target is "one
+ * conversation at a time on a single GPU box" — `--parallel N` can still go
+ * higher than on a phone, but the model is not split across cards.
+ *
+ * These profiles are *recommendations* — the runtime selects a bundle by id
+ * and then maps the host's GPU to a `GpuProfile` to fill in llama-server
+ * flags (KV cache types, n-gpu-layers, batch sizing, MTP draft range,
+ * mlock). A non-NVIDIA host returns `null` and the runtime falls back to
+ * the catalog defaults.
+ *
+ * The KV cache type names match `LocalRuntimeKernel` / the llama.cpp fork
+ * kernel handles (`qjl1_256`, `q4_polar`, `turbo3_0`, `turbo4_0`, `q8_0`,
+ * `f16`) so that `appendOptimizationFlags` + `applyGpuProfile` can pass
+ * them straight through to `--cache-type-k` / `--cache-type-v`.
+ *
+ * The active mobile/local release exposes Eliza-1 2b, 4b, 9b, and 27b
+ * tiers, with larger cards recommended toward the biggest installed bundle
+ * that leaves memory headroom.
+ */
+import type { Eliza1TierId } from "./catalog.js";
+export type GpuProfileId = "rtx-3090" | "rtx-4090" | "rtx-5090" | "h200";
+/**
+ * KV cache type names accepted by `llama-server --cache-type-k/-v`. Mirrors
+ * the strings the buun-llama-cpp fork advertises in `CAPABILITIES.json`.
+ * Kept as a string literal union so a profile's choice is checked at
+ * compile time and propagates into the bundle manifest's `requiresKernel`
+ * set.
+ */
+export type KvCacheType = "f16" | "q8_0" | "q4_0" | "qjl1_256" | "q4_polar" | "turbo3_0" | "turbo4_0";
+export interface GpuProfile {
+    id: GpuProfileId;
+    /** Human-readable vendor card name shown to the operator. */
+    displayName: string;
+    /** Total VRAM in GiB. Used for headroom math + recommendations. */
+    vramGb: number;
+    /** CUDA compute capability, e.g. `"sm_86"`. */
+    computeCapability: string;
+    /** Peak HBM/GDDR bandwidth in GB/s — feeds the perf estimator. */
+    memoryBandwidthGBs: number;
+    /** Whether the GPU has hardware FP8 (Ada/Hopper/Blackwell). */
+    fp8: boolean;
+    /**
+     * Recommended catalog bundle ids for single-GPU deployment on this card.
+     * Ordered by quality: first entry is the "best fit" for the card; later
+     * entries are smaller fallbacks that still leave headroom. The recommender
+     * picks the first id that the user has installed.
+     */
+    recommendedBundles: ReadonlyArray<Eliza1TierId>;
+    /** Inference flags. */
+    flashAttn: boolean;
+    /** `--cache-type-k` value. */
+    kvCacheTypeK: KvCacheType;
+    /** `--cache-type-v` value. */
+    kvCacheTypeV: KvCacheType;
+    /**
+     * `--n-gpu-layers` — `-1` for "all layers on GPU". Single-GPU only; we
+     * never split layers across two cards.
+     */
+    nGpuLayers: number;
+    /**
+     * `--ctx-size`. Always sized to the bundle's `contextLength`, but the
+     * profile records the *recommended* max for the card.
+     */
+    contextSize: number;
+    /** `--parallel N` continuous-batching slots. */
+    parallel: number;
+    /** `--batch-size N` logical batch. */
+    batchSize: number;
+    /** `--ubatch-size N` physical micro-batch. */
+    ubatchSize: number;
+    /** MTP speculative-decoding draft range. */
+    mtpDraftMin: number;
+    mtpDraftMax: number;
+    /** `--mlock` — pin model pages in RAM. */
+    mlock: boolean;
+    /** `--no-mmap` — disable mmap loading. */
+    noMmap: boolean;
+    /**
+     * Force KV spill to CPU (`--no-kv-offload`). Only useful on cards that
+     * cannot hold the full KV cache. The 141 GiB H200 sets this to `false`;
+     * the 24 GiB cards can opt in for very long contexts.
+     */
+    kvSpillToCpu: boolean;
+}
+export declare const GPU_PROFILES: Readonly<Record<GpuProfileId, GpuProfile>>;
+export declare const GPU_PROFILE_IDS: ReadonlyArray<GpuProfileId>;
+/**
+ * Match an `nvidia-smi --query-gpu=name` output line to a profile. Returns
+ * `null` when the card is not in the supported set; callers should fall
+ * back to the catalog defaults in that case rather than guess.
+ *
+ * The patterns are intentionally strict to avoid mis-classifying a 3080
+ * as a 3090, or an A100 as a 4090.
+ */
+export declare function matchGpuProfile(gpuName: string): GpuProfileId | null;
+/**
+ * Returns the headroom (in GiB) a profile reserves for the OS / driver /
+ * activations / drafter / N parallel-slot KV. Used for sizing checks
+ * before promoting a bundle to "fits" on a card.
+ *
+ * The figures are deliberate per-tier reserves, not a formula — different
+ * cards have different driver overheads (Windows display drivers steal
+ * ~1 GiB before workloads even start; H200 SXM has none).
+ */
+export declare function reservedHeadroomGb(profile: GpuProfile): number;
+//# sourceMappingURL=gpu-profiles.d.ts.map

package/local-inference/gpu-profiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu-profiles.d.ts","sourceRoot":"","sources":["../../src/local-inference/gpu-profiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;AAEzE;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GACnB,KAAK,GACL,MAAM,GACN,MAAM,GACN,UAAU,GACV,UAAU,GACV,UAAU,GACV,UAAU,CAAC;AAEf,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,YAAY,CAAC;IACjB,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kEAAkE;IAClE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,GAAG,EAAE,OAAO,CAAC;IAEb;;;;;OAKG;IACH,kBAAkB,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IAEhD,uBAAuB;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,8BAA8B;IAC9B,YAAY,EAAE,WAAW,CAAC;IAC1B,8BAA8B;IAC9B,YAAY,EAAE,WAAW,CAAC;IAC1B;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IAEnB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IAEpB,0CAA0C;IAC1C,KAAK,EAAE,OAAO,CAAC;IACf,0CAA0C;IAC1C,MAAM,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,YAAY,EAAE,OAAO,CAAC;CACvB;AAwHD,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,UAAU,CAAC,CAKnE,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,aAAa,CAAC,YAAY,CAKvD,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAOpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAW9D"}

package/local-inference/gpu-profiles.js

@@ -0,0 +1,191 @@
+/**
+ * Per-GPU deployment profiles for single-GPU Eliza-1 servers.
+ *
+ * Scope: ONE GPU per host. We do not target NVLink, tensor-parallel splits,
+ * or multi-tenant datacenter workloads. The product target is "one
+ * conversation at a time on a single GPU box" — `--parallel N` can still go
+ * higher than on a phone, but the model is not split across cards.
+ *
+ * These profiles are *recommendations* — the runtime selects a bundle by id
+ * and then maps the host's GPU to a `GpuProfile` to fill in llama-server
+ * flags (KV cache types, n-gpu-layers, batch sizing, MTP draft range,
+ * mlock). A non-NVIDIA host returns `null` and the runtime falls back to
+ * the catalog defaults.
+ *
+ * The KV cache type names match `LocalRuntimeKernel` / the llama.cpp fork
+ * kernel handles (`qjl1_256`, `q4_polar`, `turbo3_0`, `turbo4_0`, `q8_0`,
+ * `f16`) so that `appendOptimizationFlags` + `applyGpuProfile` can pass
+ * them straight through to `--cache-type-k` / `--cache-type-v`.
+ *
+ * The active mobile/local release exposes Eliza-1 2b, 4b, 9b, and 27b
+ * tiers, with larger cards recommended toward the biggest installed bundle
+ * that leaves memory headroom.
+ */
+/**
+ * RTX 3090 — Ampere, 24 GiB, no FP8.
+ *
+ * Best current release fit: Eliza-1 9B with 4B/2B fallbacks.
+ * Flash-attn helps Ampere meaningfully.
+ */
+const RTX_3090 = {
+    id: "rtx-3090",
+    displayName: "NVIDIA GeForce RTX 3090",
+    vramGb: 24,
+    computeCapability: "sm_86",
+    memoryBandwidthGBs: 936,
+    fp8: false,
+    recommendedBundles: ["eliza-1-9b", "eliza-1-4b", "eliza-1-2b"],
+    flashAttn: true,
+    // Ampere doesn't have the q4_polar kernel on the Polar fork; fall back to
+    // the Q8/Q4 KV quants which work on every sm_70+ GPU.
+    kvCacheTypeK: "q8_0",
+    kvCacheTypeV: "q4_polar",
+    nGpuLayers: -1,
+    contextSize: 65536,
+    parallel: 4,
+    batchSize: 2048,
+    ubatchSize: 512,
+    mtpDraftMin: 4,
+    mtpDraftMax: 16,
+    mlock: true,
+    noMmap: false,
+    kvSpillToCpu: false,
+};
+/**
+ * RTX 4090 — Ada Lovelace, 24 GiB, FP8 (no flash-attn-FP8 yet).
+ *
+ * Best current release fit: Eliza-1 27B with 9B/4B/2B fallbacks.
+ */
+const RTX_4090 = {
+    id: "rtx-4090",
+    displayName: "NVIDIA GeForce RTX 4090",
+    vramGb: 24,
+    computeCapability: "sm_89",
+    memoryBandwidthGBs: 1008,
+    fp8: true,
+    recommendedBundles: ["eliza-1-27b", "eliza-1-9b", "eliza-1-4b", "eliza-1-2b"],
+    flashAttn: true,
+    kvCacheTypeK: "qjl1_256",
+    kvCacheTypeV: "q4_polar",
+    nGpuLayers: -1,
+    contextSize: 131072,
+    parallel: 4,
+    batchSize: 2048,
+    ubatchSize: 512,
+    mtpDraftMin: 4,
+    mtpDraftMax: 24,
+    mlock: true,
+    noMmap: false,
+    kvSpillToCpu: false,
+};
+/**
+ * RTX 5090 — Blackwell, 32 GiB, FP8/FP4 first-class.
+ *
+ * Best current release fit: Eliza-1 27B. Blackwell sm_120 is new enough that
+ * the Polar/QJL kernels may not be pre-built — the runtime should probe
+ * `CAPABILITIES.json` and surface a structured error rather than silently
+ * falling back.
+ */
+const RTX_5090 = {
+    id: "rtx-5090",
+    displayName: "NVIDIA GeForce RTX 5090",
+    vramGb: 32,
+    computeCapability: "sm_120",
+    memoryBandwidthGBs: 1792,
+    fp8: true,
+    recommendedBundles: ["eliza-1-27b", "eliza-1-9b", "eliza-1-4b", "eliza-1-2b"],
+    flashAttn: true,
+    kvCacheTypeK: "qjl1_256",
+    kvCacheTypeV: "q4_polar",
+    nGpuLayers: -1,
+    contextSize: 131072,
+    parallel: 8,
+    batchSize: 4096,
+    ubatchSize: 1024,
+    mtpDraftMin: 4,
+    mtpDraftMax: 24,
+    mlock: true,
+    noMmap: false,
+    kvSpillToCpu: false,
+};
+/**
+ * H200 — Hopper, 141 GiB HBM3e, 4.8 TB/s.
+ *
+ * Best current release fit: Eliza-1 27B.
+ */
+const H200 = {
+    id: "h200",
+    displayName: "NVIDIA H200 (SXM 141 GiB)",
+    vramGb: 141,
+    computeCapability: "sm_90",
+    memoryBandwidthGBs: 4800,
+    fp8: true,
+    recommendedBundles: ["eliza-1-27b", "eliza-1-9b", "eliza-1-4b", "eliza-1-2b"],
+    flashAttn: true,
+    kvCacheTypeK: "qjl1_256",
+    kvCacheTypeV: "q4_polar",
+    nGpuLayers: -1,
+    contextSize: 131072,
+    parallel: 16,
+    batchSize: 4096,
+    ubatchSize: 2048,
+    mtpDraftMin: 8,
+    mtpDraftMax: 32,
+    mlock: true,
+    noMmap: false,
+    kvSpillToCpu: false,
+};
+export const GPU_PROFILES = {
+    "rtx-3090": RTX_3090,
+    "rtx-4090": RTX_4090,
+    "rtx-5090": RTX_5090,
+    h200: H200,
+};
+export const GPU_PROFILE_IDS = [
+    "rtx-3090",
+    "rtx-4090",
+    "rtx-5090",
+    "h200",
+];
+/**
+ * Match an `nvidia-smi --query-gpu=name` output line to a profile. Returns
+ * `null` when the card is not in the supported set; callers should fall
+ * back to the catalog defaults in that case rather than guess.
+ *
+ * The patterns are intentionally strict to avoid mis-classifying a 3080
+ * as a 3090, or an A100 as a 4090.
+ */
+export function matchGpuProfile(gpuName) {
+    const n = gpuName.toLowerCase();
+    if (n.includes("h200"))
+        return "h200";
+    if (n.includes("rtx 5090") || n.includes("rtx5090"))
+        return "rtx-5090";
+    if (n.includes("rtx 4090") || n.includes("rtx4090"))
+        return "rtx-4090";
+    if (n.includes("rtx 3090") || n.includes("rtx3090"))
+        return "rtx-3090";
+    return null;
+}
+/**
+ * Returns the headroom (in GiB) a profile reserves for the OS / driver /
+ * activations / drafter / N parallel-slot KV. Used for sizing checks
+ * before promoting a bundle to "fits" on a card.
+ *
+ * The figures are deliberate per-tier reserves, not a formula — different
+ * cards have different driver overheads (Windows display drivers steal
+ * ~1 GiB before workloads even start; H200 SXM has none).
+ */
+export function reservedHeadroomGb(profile) {
+    switch (profile.id) {
+        case "rtx-3090":
+            return 3;
+        case "rtx-4090":
+            return 3;
+        case "rtx-5090":
+            return 4;
+        case "h200":
+            return 6;
+    }
+}
+//# sourceMappingURL=gpu-profiles.js.map

package/local-inference/gpu-profiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu-profiles.js","sourceRoot":"","sources":["../../src/local-inference/gpu-profiles.ts"],"names":[],"mappings":"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"}

package/local-inference/hf-proxy.d.ts

@@ -0,0 +1,43 @@
+/**
+ * HuggingFace download routing for local-inference bundle fetches.
+ *
+ * The product never holds a local HuggingFace token. When the device is linked
+ * to Eliza Cloud, ALL HuggingFace `resolve` traffic is routed through the cloud
+ * HF proxy (`/api/v1/hf-proxy/<repo>/resolve/<rev>/<path>`), which attaches the
+ * cloud-side `HF_TOKEN` so gated repos resolve without exposing a token to the
+ * client. When the device is not cloud-linked, downloads go directly to the
+ * public (ungated) HuggingFace host — the shipping eliza-1 bundles are public.
+ *
+ * Precedence:
+ *   1. `ELIZA_HF_BASE_URL` override (explicit mirror/base) — always wins.
+ *   2. Cloud proxy base + bearer — when an Eliza Cloud API key is present.
+ *   3. Direct public HuggingFace host — no auth header.
+ *
+ * The returned `base` is the host (+ optional path prefix) that a
+ * `<repo>/resolve/<rev>/<path>` suffix is appended to by the catalog URL
+ * builder, so cloud and direct paths share one URL-construction shape.
+ */
+export interface HfDownloadBase {
+    /**
+     * Base URL the catalog builder appends `<repo>/resolve/<rev>/<path>` to.
+     * For the cloud proxy this is `<cloudApi>/hf-proxy`; for direct HF it is the
+     * HuggingFace host. Never has a trailing slash.
+     */
+    base: string;
+    /**
+     * Bearer header to send with the request, or `undefined` for the
+     * unauthenticated public path. Only the cloud proxy carries auth — the
+     * cloud-side `HF_TOKEN` is attached by the Worker, never by the client.
+     */
+    authHeader?: {
+        authorization: string;
+    };
+    /** True when traffic is routed through the Eliza Cloud HF proxy. */
+    viaCloud: boolean;
+}
+/**
+ * Resolve where HuggingFace `resolve` traffic should go and how it should
+ * authenticate. See the module doc for precedence.
+ */
+export declare function resolveHfDownloadBase(): HfDownloadBase;
+//# sourceMappingURL=hf-proxy.d.ts.map

package/local-inference/hf-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hf-proxy.d.ts","sourceRoot":"","sources":["../../src/local-inference/hf-proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAOH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,UAAU,CAAC,EAAE;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAC;CACnB;AAWD;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,cAAc,CAiBtD"}

package/local-inference/hf-proxy.js

@@ -0,0 +1,50 @@
+/**
+ * HuggingFace download routing for local-inference bundle fetches.
+ *
+ * The product never holds a local HuggingFace token. When the device is linked
+ * to Eliza Cloud, ALL HuggingFace `resolve` traffic is routed through the cloud
+ * HF proxy (`/api/v1/hf-proxy/<repo>/resolve/<rev>/<path>`), which attaches the
+ * cloud-side `HF_TOKEN` so gated repos resolve without exposing a token to the
+ * client. When the device is not cloud-linked, downloads go directly to the
+ * public (ungated) HuggingFace host — the shipping eliza-1 bundles are public.
+ *
+ * Precedence:
+ *   1. `ELIZA_HF_BASE_URL` override (explicit mirror/base) — always wins.
+ *   2. Cloud proxy base + bearer — when an Eliza Cloud API key is present.
+ *   3. Direct public HuggingFace host — no auth header.
+ *
+ * The returned `base` is the host (+ optional path prefix) that a
+ * `<repo>/resolve/<rev>/<path>` suffix is appended to by the catalog URL
+ * builder, so cloud and direct paths share one URL-construction shape.
+ */
+import { resolveCloudApiBaseUrl } from "../elizacloud/base-url.js";
+import { getCloudSecret } from "../elizacloud/cloud-secrets.js";
+const DEFAULT_HF_HOST = "https://huggingface.co";
+function trimTrailingSlash(value) {
+    return value.replace(/\/+$/, "");
+}
+/** Read the Eliza Cloud API key from the sealed store (falls back to env). */
+function cloudApiKey() {
+    return getCloudSecret("ELIZAOS_CLOUD_API_KEY")?.trim() ?? "";
+}
+/**
+ * Resolve where HuggingFace `resolve` traffic should go and how it should
+ * authenticate. See the module doc for precedence.
+ */
+export function resolveHfDownloadBase() {
+    const override = process.env.ELIZA_HF_BASE_URL?.trim();
+    if (override) {
+        return { base: trimTrailingSlash(override), viaCloud: false };
+    }
+    const apiKey = cloudApiKey();
+    if (apiKey) {
+        const cloudApi = resolveCloudApiBaseUrl(process.env.ELIZAOS_CLOUD_BASE_URL);
+        return {
+            base: `${trimTrailingSlash(cloudApi)}/hf-proxy`,
+            authHeader: { authorization: `Bearer ${apiKey}` },
+            viaCloud: true,
+        };
+    }
+    return { base: DEFAULT_HF_HOST, viaCloud: false };
+}
+//# sourceMappingURL=hf-proxy.js.map

package/local-inference/hf-proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hf-proxy.js","sourceRoot":"","sources":["../../src/local-inference/hf-proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAEhE,MAAM,eAAe,GAAG,wBAAwB,CAAC;AAmBjD,SAAS,iBAAiB,CAAC,KAAa;IACtC,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACnC,CAAC;AAED,8EAA8E;AAC9E,SAAS,WAAW;IAClB,OAAO,cAAc,CAAC,uBAAuB,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,IAAI,EAAE,CAAC;IACvD,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,iBAAiB,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAChE,CAAC;IAED,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC;IAC7B,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,QAAQ,GAAG,sBAAsB,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC;QAC5E,OAAO;YACL,IAAI,EAAE,GAAG,iBAAiB,CAAC,QAAQ,CAAC,WAAW;YAC/C,UAAU,EAAE,EAAE,aAAa,EAAE,UAAU,MAAM,EAAE,EAAE;YACjD,QAAQ,EAAE,IAAI;SACf,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AACpD,CAAC"}

package/local-inference/hub-auth.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Model-hub authentication helpers.
+ *
+ * Gated/metered HuggingFace repos require an `Authorization: Bearer <token>`
+ * header or they answer `HTTP 401`/`403` (and gated repos are invisible to
+ * unauthenticated search, reporting wrong/zero sizes). The token is read from
+ * the same env aliases the embedding manager uses
+ * (`HF_TOKEN` / `HUGGINGFACE_TOKEN` / `HF_HUB_TOKEN`).
+ *
+ * The token is **host-gated**: it is only attached to `huggingface.co`
+ * requests, never leaked to ModelScope or arbitrary mirrors. Every model
+ * download and search path forwards it through {@link resolveHubAuthHeaders}.
+ */
+/** Read the HuggingFace token from the documented env aliases. `""` when unset. */
+export declare function resolveHuggingFaceToken(): string;
+/** True when a configured HuggingFace token is present in the environment. */
+export declare function hasHuggingFaceToken(): boolean;
+/** True when `url` points at huggingface.co (or a subdomain of it). */
+export declare function isHuggingFaceHost(url: string): boolean;
+/**
+ * Auth headers for a model-hub request. Returns the bearer header only for
+ * huggingface.co URLs when a token is configured; `{}` otherwise (public repos
+ * and non-HF hosts are unaffected, and tokens never leak to other hosts).
+ */
+export declare function resolveHubAuthHeaders(url: string): Record<string, string>;
+//# sourceMappingURL=hub-auth.d.ts.map

package/local-inference/hub-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub-auth.d.ts","sourceRoot":"","sources":["../../src/local-inference/hub-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,mFAAmF;AACnF,wBAAgB,uBAAuB,IAAI,MAAM,CAQhD;AAED,8EAA8E;AAC9E,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOtD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIzE"}

package/local-inference/hub-auth.js

@@ -0,0 +1,48 @@
+/**
+ * Model-hub authentication helpers.
+ *
+ * Gated/metered HuggingFace repos require an `Authorization: Bearer <token>`
+ * header or they answer `HTTP 401`/`403` (and gated repos are invisible to
+ * unauthenticated search, reporting wrong/zero sizes). The token is read from
+ * the same env aliases the embedding manager uses
+ * (`HF_TOKEN` / `HUGGINGFACE_TOKEN` / `HF_HUB_TOKEN`).
+ *
+ * The token is **host-gated**: it is only attached to `huggingface.co`
+ * requests, never leaked to ModelScope or arbitrary mirrors. Every model
+ * download and search path forwards it through {@link resolveHubAuthHeaders}.
+ */
+/** Read the HuggingFace token from the documented env aliases. `""` when unset. */
+export function resolveHuggingFaceToken() {
+    if (typeof process === "undefined" || !process.env)
+        return "";
+    return (process.env.HF_TOKEN?.trim() ||
+        process.env.HUGGINGFACE_TOKEN?.trim() ||
+        process.env.HF_HUB_TOKEN?.trim() ||
+        "");
+}
+/** True when a configured HuggingFace token is present in the environment. */
+export function hasHuggingFaceToken() {
+    return resolveHuggingFaceToken().length > 0;
+}
+/** True when `url` points at huggingface.co (or a subdomain of it). */
+export function isHuggingFaceHost(url) {
+    try {
+        const host = new URL(url).hostname.toLowerCase();
+        return host === "huggingface.co" || host.endsWith(".huggingface.co");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Auth headers for a model-hub request. Returns the bearer header only for
+ * huggingface.co URLs when a token is configured; `{}` otherwise (public repos
+ * and non-HF hosts are unaffected, and tokens never leak to other hosts).
+ */
+export function resolveHubAuthHeaders(url) {
+    if (!isHuggingFaceHost(url))
+        return {};
+    const token = resolveHuggingFaceToken();
+    return token ? { authorization: `Bearer ${token}` } : {};
+}
+//# sourceMappingURL=hub-auth.js.map

package/local-inference/hub-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub-auth.js","sourceRoot":"","sources":["../../src/local-inference/hub-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,mFAAmF;AACnF,MAAM,UAAU,uBAAuB;IACrC,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,CAAC,OAAO,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC;IAC9D,OAAO,CACL,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE;QAC5B,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,IAAI,EAAE;QACrC,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,EAAE;QAChC,EAAE,CACH,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,mBAAmB;IACjC,OAAO,uBAAuB,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AAC9C,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;QACjD,OAAO,IAAI,KAAK,gBAAgB,IAAI,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;IACvE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IACvC,MAAM,KAAK,GAAG,uBAAuB,EAAE,CAAC;IACxC,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC3D,CAAC"}