@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.3-beta.3

package/dist/services/device-tier.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Device-tier classifier — maps a `HardwareProbe` to a `DeviceTier`
+ * (`MAX | GOOD | OKAY | POOR`) and produces the warning copy + the
+ * recommended local-voice policy the runtime + UI consume.
+ *
+ * Single-pass classifier (no async I/O). The host probe already happened in
+ * `hardware.ts`; this module is pure arithmetic on top of the probe.
+ *
+ * Numeric thresholds and tier definitions are sourced verbatim from R9
+ * (`.swarm/research/R9-memory.md` §3.1) — keep this file's per-tier table
+ * in sync with that document.
+ *
+ *   - **MAX** — all voice + LM models can be **parallelized** and held
+ *     resident at once (~24 GB effective model RAM AND ≥ 16 GB free at
+ *     session start AND a dGPU with ≥ 16 GB VRAM OR an Apple Silicon
+ *     Pro/Max/Ultra with ≥ 32 GB shared RAM).
+ *   - **GOOD** — all models can be loaded into memory and run, but
+ *     serialized (~12 GB effective model RAM AND ≥ 8 GB free at session
+ *     start AND a dGPU with ≥ 8 GB VRAM, OR Apple Silicon base ≥ 16 GB,
+ *     OR x86 CPU-only ≥ 32 GB).
+ *   - **OKAY** — models load and unload per turn; caching breaks across
+ *     swaps (~6 GB effective model RAM AND ≥ 3 GB free).
+ *   - **POOR** — severe issues; refuse local voice, recommend cloud.
+ *
+ * Mobile clamps to **OKAY** at best regardless of RAM because the OS
+ * background-task model breaks long-running local inference (iOS jetsam
+ * 3–4 GB ceiling; Android foreground-service requirement).
+ */
+import { type Eliza1Fit } from "@elizaos/shared/local-inference";
+import type { HardwareProbe } from "./types";
+/** The four device tiers used by the runtime + UI. */
+export type DeviceTier = "MAX" | "GOOD" | "OKAY" | "POOR";
+/** Tier ordering (higher index = better device). */
+export declare const DEVICE_TIER_ORDER: ReadonlyArray<DeviceTier>;
+/**
+ * Numeric thresholds. R9 §3.1 — keep in sync.
+ *
+ * "Effective model memory" is the memory the model can actually use, in GB.
+ * The math mirrors `recommendation.ts:effectiveMemoryGb()`:
+ *   - Apple Silicon: `totalRamGb`.
+ *   - Discrete GPU: `max(gpu.totalVramGb, totalRamGb * 0.5)`.
+ *   - CPU-only:     `totalRamGb * 0.5`.
+ */
+export declare const DEVICE_TIER_THRESHOLDS: {
+    readonly MAX: {
+        readonly effectiveModelMemoryGb: 24;
+        readonly freeRamGbAtSession: 16;
+        readonly dGpuMinVramGb: 16;
+        readonly appleSiliconMinMemoryGb: 32;
+    };
+    readonly GOOD: {
+        readonly effectiveModelMemoryGb: 12;
+        readonly freeRamGbAtSession: 8;
+        readonly dGpuMinVramGb: 8;
+        readonly appleSiliconMinMemoryGb: 16;
+        readonly x86CpuOnlyMinTotalGb: 32;
+    };
+    readonly OKAY: {
+        readonly effectiveModelMemoryGb: 6;
+        readonly freeRamGbAtSession: 3;
+        readonly minTotalRamGb: 16;
+        readonly mobileMinTotalRamGb: 6;
+        readonly mobileEffectiveModelMemoryGb: 3;
+    };
+};
+/** What the runtime should do by default given the tier classification. */
+export type RecommendedMode = "local" | "cloud-with-local-voice" | "cloud-only";
+/** A complete tier assessment — what the UI renders + what the runtime gates on. */
+export interface DeviceTierAssessment {
+    tier: DeviceTier;
+    /** Human-readable reasons for the decision. */
+    reasons: string[];
+    /** The top recommendation for the user, in plain text. */
+    topRecommendation: string;
+    /** True when local LM (eliza-1) is viable at the user's tier. */
+    canRunLocalLm: boolean;
+    /** True when the local voice stack (ASR + TTS) is viable. */
+    canRunLocalVoice: boolean;
+    /** Default backend mode for the user. */
+    recommendedMode: RecommendedMode;
+    /**
+     * The biggest eliza-1 tier (+ 128k-targeted QJL context) that fits this device,
+     * or `null` when nothing local fits and the modality should route to Cloud.
+     * This is the single forced-model decision the consumer UI renders read-only.
+     */
+    recommendedFit: Eliza1Fit | null;
+    /** Numeric snapshot to drive UI badges and first-run copy. */
+    numericContext: {
+        totalRamGb: number;
+        freeRamGb: number;
+        effectiveModelMemoryGb: number;
+        vramGb: number | null;
+        cpuCores: number;
+        appleSilicon: boolean;
+        mobile: boolean;
+    };
+}
+/**
+ * Compute the memory the model can actually use, in GB. Apple Silicon uses
+ * shared memory; discrete-GPU x86 weights VRAM; CPU-only halves total RAM.
+ * Mirrors `recommendation.ts:effectiveMemoryGb`.
+ */
+export declare function effectiveModelMemoryGb(probe: HardwareProbe): number;
+/**
+ * The canonical "biggest eliza-1 that fits this device" decision: normalize the
+ * hardware probe to usable model memory, then pick the largest tier at a 128k QJL
+ * window (or a downscaled 2B window, or `null` → route to Cloud). This is the one
+ * function callers should use to answer "what local model runs here" — it always
+ * applies TurboQuant weights + the QJL KV cache and targets a 128k window. On
+ * mobile it caps the tier at 4B and the context at 64k (a phone cannot hold a 128k
+ * cache).
+ */
+export declare function selectBestEliza1FitForDevice(probe: HardwareProbe): Eliza1Fit | null;
+/**
+ * The single-pass classifier. Returns a complete assessment including the
+ * tier, the reasons, the recommended default mode, and the numeric context
+ * the UI needs to render the badge.
+ *
+ * The classifier is pure: same input → same output, no I/O, no clock.
+ */
+export declare function classifyDeviceTier(probe: HardwareProbe): DeviceTierAssessment;
+/**
+ * Warning-copy strings for each tier. The exact prose comes from R9 §7;
+ * I10 surfaces these via the `voice-tier.json` i18n bundle. Keep this in
+ * sync with `packages/ui/src/i18n/voice-tier.json`.
+ */
+export declare const TIER_WARNING_COPY: Readonly<Record<DeviceTier, {
+    header: string;
+    body: string;
+}>>;
+/** Convenience: total RAM in MB. */
+export declare function totalRamMb(probe: HardwareProbe): number;
+//# sourceMappingURL=device-tier.d.ts.map

package/dist/services/device-tier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-tier.d.ts","sourceRoot":"","sources":["../../src/services/device-tier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EACN,KAAK,SAAS,EAKd,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,sDAAsD;AACtD,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1D,oDAAoD;AACpD,eAAO,MAAM,iBAAiB,EAAE,aAAa,CAAC,UAAU,CAKvD,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;CAwBzB,CAAC;AAEX,2EAA2E;AAC3E,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,wBAAwB,GAAG,YAAY,CAAC;AAEhF,oFAAoF;AACpF,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,UAAU,CAAC;IACjB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0DAA0D;IAC1D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iEAAiE;IACjE,aAAa,EAAE,OAAO,CAAC;IACvB,6DAA6D;IAC7D,gBAAgB,EAAE,OAAO,CAAC;IAC1B,yCAAyC;IACzC,eAAe,EAAE,eAAe,CAAC;IACjC;;;;OAIG;IACH,cAAc,EAAE,SAAS,GAAG,IAAI,CAAC;IACjC,8DAA8D;IAC9D,cAAc,EAAE;QACf,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,sBAAsB,EAAE,MAAM,CAAC;QAC/B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,OAAO,CAAC;QACtB,MAAM,EAAE,OAAO,CAAC;KAChB,CAAC;CACF;AAID;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAMnE;AA4BD;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC3C,KAAK,EAAE,aAAa,GAClB,SAAS,GAAG,IAAI,CA2BlB;AAgDD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,GAAG,oBAAoB,CA+E7E;AAsID;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CACvC,MAAM,CACL,UAAU,EACV;IACC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACb,CACD,CAkBD,CAAC;AAEF,oCAAoC;AACpC,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAEvD"}

package/dist/services/downloader.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Resumable GGUF downloader.
+ *
+ * Streams directly from HuggingFace to a staging file under
+ * `$STATE_DIR/local-inference/downloads/<id>.part`, then atomically moves
+ * it into `models/<id>.gguf` on success. On restart the staging file is
+ * still there; `resumeIfPossible` sends a Range request starting at the
+ * current partial size.
+ *
+ * Concurrency model: at most one download per model id. Callers use
+ * `subscribe()` to receive progress events; the service facade wires that
+ * to SSE.
+ *
+ * The runtime `fetch` follows HuggingFace redirects and still gives us a body
+ * stream that can be piped into a Node WriteStream.
+ */
+import { type Eliza1DeviceCaps } from "./manifest";
+import { type CatalogModel, type DownloadEvent, type DownloadJob, type HardwareProbe } from "./types";
+type DownloadListener = (event: DownloadEvent) => void;
+/**
+ * Thrown before any weight byte is fetched when an Eliza-1 bundle's manifest
+ * is incompatible with this device — wrong schema version, no overlapping
+ * verified backend, or a RAM budget that exceeds the device's memory. Per
+ * `packages/inference/AGENTS.md` §7 there is no "download anyway" path.
+ */
+export declare class BundleIncompatibleError extends Error {
+    readonly code: "ELIZA1_BUNDLE_INCOMPATIBLE";
+    constructor(message: string);
+}
+/**
+ * One-time verify-on-device pass per `packages/inference/AGENTS.md` §7:
+ * load → 1-token text generation → 1-phrase voice generation → barge-in
+ * cancel. The downloader stays decoupled from the engine — the service
+ * layer injects this; when absent the bundle is materialized and registered
+ * but its `bundleVerifiedAt` stays unset and it does NOT auto-fill an empty
+ * default slot (an unverified bundle must not become the recommended
+ * default).
+ */
+export type VerifyBundleOnDevice = (args: {
+    modelId: string;
+    bundleRoot: string;
+    manifestPath: string;
+    textGgufPath: string;
+}) => Promise<void>;
+export interface DownloaderOptions {
+    /** Override the device-capability probe (tests / headless environments). */
+    probeDeviceCaps?: () => Promise<Eliza1DeviceCaps>;
+    /** Verify-on-device smoke run; see {@link VerifyBundleOnDevice}. */
+    verifyOnDevice?: VerifyBundleOnDevice;
+    /** Override the hardware probe used by the disk-space preflight (tests). */
+    probeHardware?: () => Promise<HardwareProbe>;
+}
+export declare class Downloader {
+    private readonly active;
+    private readonly terminal;
+    private readonly listeners;
+    private readonly lastEmit;
+    private readonly probeDeviceCaps;
+    private readonly verifyOnDevice?;
+    private readonly probeHardware;
+    constructor(options?: DownloaderOptions);
+    subscribe(listener: DownloadListener): () => void;
+    snapshot(): DownloadJob[];
+    isActive(modelId: string): boolean;
+    /**
+     * Start a download for a curated Eliza-1 catalog entry. Object specs are
+     * accepted only for internal tests that decorate a known Eliza-1 id; ad-hoc
+     * Hugging Face / ModelScope specs are rejected before any reservation or
+     * network I/O.
+     */
+    start(modelIdOrSpec: string | CatalogModel): Promise<DownloadJob>;
+    cancel(modelId: string): boolean;
+    private emit;
+    private updateState;
+    private loadTerminalDownloads;
+    private persistTerminalDownloads;
+    private rememberTerminalDownload;
+    private clearTerminalDownload;
+    private throttleEmit;
+    /**
+     * Disk-space preflight. The remaining download must fit on the models
+     * volume with a small headroom margin, or we fail the job up front with an
+     * actionable message instead of letting it stream gigabytes and die with
+     * ENOSPC near the end. Best-effort: when free disk can't be probed we let
+     * the download proceed (the post-hoc ENOSPC handling still catches it).
+     */
+    private assertDiskSpaceForJob;
+    private runJob;
+    private runBundleJob;
+    private downloadRemotePath;
+    private loadHttpClient;
+}
+export {};
+//# sourceMappingURL=downloader.d.ts.map

package/dist/services/downloader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"downloader.d.ts","sourceRoot":"","sources":["../../src/services/downloader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAuBH,OAAO,EACN,KAAK,gBAAgB,EAMrB,MAAM,YAAY,CAAC;AAOpB,OAAO,EACN,KAAK,YAAY,EAEjB,KAAK,aAAa,EAClB,KAAK,WAAW,EAEhB,KAAK,aAAa,EAElB,MAAM,SAAS,CAAC;AAUjB,KAAK,gBAAgB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAGvD;;;;;GAKG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IACjD,QAAQ,CAAC,IAAI,EAAG,4BAA4B,CAAU;gBAC1C,OAAO,EAAE,MAAM;CAI3B;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,IAAI,EAAE;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACrB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEpB,MAAM,WAAW,iBAAiB;IACjC,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAClD,oEAAoE;IACpE,cAAc,CAAC,EAAE,oBAAoB,CAAC;IACtC,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;CAC7C;AA4MD,qBAAa,UAAU;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;IACvD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAC3D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA+B;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkC;IAClE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAuB;IACvD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA+B;gBAEjD,OAAO,GAAE,iBAAsB;IAO3C,SAAS,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,IAAI;IAOjD,QAAQ,IAAI,WAAW,EAAE;IAUzB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAQlC;;;;;OAKG;IACG,KAAK,CAAC,aAAa,EAAE,MAAM,GAAG,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAyEvE,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAchC,OAAO,CAAC,IAAI;IAWZ,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,qBAAqB;IAwB7B,OAAO,CAAC,wBAAwB;IAkBhC,OAAO,CAAC,wBAAwB;IAYhC,OAAO,CAAC,qBAAqB;IAK7B,OAAO,CAAC,YAAY;IAQpB;;;;;;OAMG;YACW,qBAAqB;YAqBrB,MAAM;YAwJN,YAAY;YAmLZ,kBAAkB;YAkHlB,cAAc;CAkC5B"}