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

package/src/services/ram-budget.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Resolve a model's RAM budget and decide whether it fits the host.
+ *
+ * For installed Eliza-1 tiers WITH a published `eliza-1.manifest.json`
+ * on disk we prefer the manifest's `ramBudgetMb.{min, recommended}`
+ * block — that's what packages/inference/AGENTS.md §3 + §6 designate
+ * as the source of truth for per-bundle memory expectations. For every
+ * other model (non-Eliza-1, uninstalled tiers, or Eliza-1 bundles that
+ * predate the manifest publish) we fall back to the catalog scalar
+ * `model.minRamGb` for the floor and synthesize a `recommendedMb` from
+ * the floor plus the bundle's per-token KV-cache footprint at its default
+ * context window — the same `KvGeometry` figure `kv-spill.ts` uses. That
+ * fixes the degenerate `minMb == recommendedMb` catalog case: a long
+ * session grows into the KV cache, so "boots" and "runs comfortably" are
+ * genuinely different lines.
+ *
+ * The manifest read is best-effort: a missing or malformed manifest
+ * never throws — recommendation runs at runtime and a broken manifest
+ * must not crash the dashboard. Build-time gates live in the publish
+ * script (packages/training/scripts/manifest/eliza1_manifest.py) and
+ * the validator (`./manifest/validator.ts`).
+ *
+ * This module is the single source of truth for the "does model X fit a
+ * host with N MB usable RAM" decision (`assessRamFit`). Both the Model
+ * Hub recommender (`recommendation.ts`) and the model-load admission gate
+ * (`active-model.ts`) call it — neither re-derives the math.
+ */
+import { type Eliza1Manifest } from "./manifest";
+import type { CatalogModel, InstalledModel, RamBudget } from "./types";
+export declare function ramHeadroomReserveMb(): number;
+export type { RamBudget } from "./types.js";
+/**
+ * Loader contract — keeps the helper testable without touching disk.
+ * Production callers pass `defaultManifestLoader`; tests inject a fake loader.
+ */
+export type ManifestLoader = (modelId: string, installed: InstalledModel | undefined) => Eliza1Manifest | null;
+/** Test-only: drop memoized manifests so fixtures with reused SHAs don't leak. */
+export declare function __resetManifestCacheForTests(): void;
+/**
+ * Production manifest loader — reads `eliza-1.manifest.json` from the
+ * installed bundle's directory. Two candidate paths are probed:
+ *
+ *   1. `dirname(dirname(model.path))` — the canonical bundle root when
+ *      the GGUF lives in a `text/` subdir per AGENTS.md §2.
+ *   2. `dirname(model.path)` — flat layout used by some test fixtures
+ *      and pre-bundle installs.
+ *
+ * Returns `null` for any failure: missing file, JSON parse error,
+ * manifest validation error, or tier mismatch.
+ */
+export declare function defaultManifestLoader(modelId: string, installed: InstalledModel | undefined): Eliza1Manifest | null;
+/**
+ * Resolve a `RamBudget` for `model`, optionally consulting the on-disk
+ * manifest of an installed Eliza-1 bundle.
+ *
+ * `installed` and `manifestLoader` are both optional — passing neither
+ * always returns the catalog-scalar fallback. The recommendation engine
+ * passes both at call sites where it has the installed-models list.
+ */
+export declare function resolveRamBudget(model: CatalogModel, installed?: InstalledModel, manifestLoader?: ManifestLoader): RamBudget;
+export interface RamFitOptions {
+    installed?: InstalledModel;
+    manifestLoader?: ManifestLoader;
+    /**
+     * Override the headroom reserved for the OS/runtime. Defaults to
+     * `ramHeadroomReserveMb()`. Pass 0 to assess against raw memory (the
+     * recommender does this — it works in "effective memory available to
+     * the model" terms, where the OS reserve is already discounted).
+     */
+    reserveMb?: number;
+}
+export type RamFitLevel = "fits" | "tight" | "wontfit";
+export interface RamFitDecision {
+    level: RamFitLevel;
+    /** True for `fits` and `tight`; false only for `wontfit`. */
+    fits: boolean;
+    budget: RamBudget;
+    /** Memory after subtracting the headroom reserve, in MB. */
+    usableMb: number;
+    /** Headroom reserve applied, in MB. */
+    reserveMb: number;
+}
+/**
+ * The one fit decision. `hostRamMb` is the memory being assessed against,
+ * in megabytes (`os.totalmem() / 2**20`, or the probe's `totalRamGb * 1024`,
+ * or — for the recommender on a GPU host — the effective model-available
+ * memory in MB).
+ *
+ *   - `wontfit` : usable RAM (host minus headroom) is below the bundle's
+ *                 boot floor (`budget.minMb`). A load MUST be refused.
+ *   - `tight`   : boots, but usable RAM is below the recommended budget —
+ *                 a long session will swap or stutter under load.
+ *   - `fits`    : comfortable headroom.
+ */
+export declare function assessRamFit(model: CatalogModel, hostRamMb: number, options?: RamFitOptions): RamFitDecision;
+/**
+ * Given a catalog entry, pick the variant of the same model "line" (same
+ * param count and display-name stem — e.g. `eliza-1-27b` / `eliza-1-27b-256k`)
+ * with the largest context window that still fits a
+ * host with `hostRamMb` of RAM. Returns `model` itself when it's already
+ * the best fit (or the only variant), or `null` when not even `model` fits
+ * — callers turn that into a refusal.
+ *
+ * Variants are matched by `(params, displayNameStem)` where the stem is the
+ * display name with any trailing `-<ctx>` suffix (`-256k`, `-1m`, `-128k`)
+ * stripped. This keeps `eliza-1-27b*` together without conflating `9b` and
+ * `27b`.
+ */
+export declare function pickFittingContextVariant(model: CatalogModel, hostRamMb: number, options?: RamFitOptions, catalog?: ReadonlyArray<CatalogModel>): CatalogModel | null;
+//# sourceMappingURL=ram-budget.d.ts.map

package/src/services/ram-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ram-budget.d.ts","sourceRoot":"","sources":["ram-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH,OAAO,EAAE,KAAK,cAAc,EAAoB,MAAM,YAAY,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAoBvE,wBAAgB,oBAAoB,IAAI,MAAM,CAO7C;AAED,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAC5B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,cAAc,GAAG,SAAS,KACjC,cAAc,GAAG,IAAI,CAAC;AAmB3B,kFAAkF;AAClF,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD;AAOD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,cAAc,GAAG,SAAS,GACnC,cAAc,GAAG,IAAI,CAyCvB;AAkBD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE,YAAY,EACnB,SAAS,CAAC,EAAE,cAAc,EAC1B,cAAc,GAAE,cAAsC,GACpD,SAAS,CAiBX;AAED,MAAM,WAAW,aAAa;IAC7B,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAEvD,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,WAAW,CAAC;IACnB,6DAA6D;IAC7D,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,SAAS,CAAC;IAClB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC3B,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,aAAkB,GACzB,cAAc,CAmBhB;AAOD;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACxC,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,aAAkB,EAC3B,OAAO,GAAE,aAAa,CAAC,YAAY,CAAiB,GAClD,YAAY,GAAG,IAAI,CAkBrB"}

package/src/services/readiness.d.ts

@@ -0,0 +1,9 @@
+import type { ActiveModelState, CatalogModel, DownloadJob, InstalledModel, LocalInferenceReadiness, ModelAssignments } from "./types";
+export declare function buildTextGenerationReadiness(input: {
+    assignments: ModelAssignments;
+    installed: InstalledModel[];
+    active: ActiveModelState;
+    downloads: DownloadJob[];
+    catalog?: CatalogModel[];
+}): LocalInferenceReadiness;
+//# sourceMappingURL=readiness.d.ts.map

package/src/services/readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["readiness.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACX,gBAAgB,EAChB,YAAY,EACZ,WAAW,EAEX,cAAc,EAEd,uBAAuB,EAEvB,gBAAgB,EAEhB,MAAM,SAAS,CAAC;AA8LjB,wBAAgB,4BAA4B,CAAC,KAAK,EAAE;IACnD,WAAW,EAAE,gBAAgB,CAAC;IAC9B,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,MAAM,EAAE,gBAAgB,CAAC;IACzB,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;CACzB,GAAG,uBAAuB,CA4B1B"}

package/src/services/readiness.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { buildTextGenerationReadiness } from "./readiness";
+import type { ActiveModelState, DownloadJob, InstalledModel } from "./types";
+
+const activeIdle: ActiveModelState = {
+	modelId: null,
+	loadedAt: null,
+	status: "idle",
+};
+
+describe("local inference text readiness", () => {
+	it("reports assigned download terminal error state", () => {
+		const installed: InstalledModel[] = [];
+		const failedDownload: DownloadJob = {
+			jobId: "job-1",
+			modelId: "eliza-1-2b",
+			state: "failed",
+			received: 128,
+			total: 512,
+			bytesPerSec: 0,
+			etaMs: null,
+			startedAt: new Date().toISOString(),
+			updatedAt: new Date().toISOString(),
+			error: "HTTP 503 from HuggingFace",
+		};
+
+		const readiness = buildTextGenerationReadiness({
+			assignments: {
+				TEXT_LARGE: "eliza-1-2b",
+			},
+			installed,
+			active: activeIdle,
+			downloads: [failedDownload],
+		});
+
+		expect(readiness.slots.TEXT_LARGE.assigned).toBe(true);
+		expect(readiness.slots.TEXT_LARGE.primaryDownloaded).toBe(false);
+		expect(readiness.slots.TEXT_LARGE.downloaded).toBe(false);
+		expect(readiness.slots.TEXT_LARGE.state).toBe("failed");
+		expect(readiness.slots.TEXT_LARGE.missingModelIds).toContain("eliza-1-2b");
+		expect(readiness.slots.TEXT_LARGE.download.percent).toBe(25);
+		expect(readiness.slots.TEXT_LARGE.errors).toContain(
+			"HTTP 503 from HuggingFace",
+		);
+	});
+
+	it("marks a downloaded active assignment ready", () => {
+		const installed: InstalledModel[] = [
+			{
+				id: "eliza-1-2b",
+				displayName: "eliza-1-2b",
+				path: "/tmp/eliza-1-2b.gguf",
+				sizeBytes: 2048,
+				installedAt: new Date().toISOString(),
+				lastUsedAt: null,
+				source: "eliza-download",
+			},
+			{
+				id: "eliza-1-2b-drafter",
+				displayName: "eliza-1-2b drafter",
+				path: "/tmp/eliza-1-2b-drafter.gguf",
+				sizeBytes: 512,
+				installedAt: new Date().toISOString(),
+				lastUsedAt: null,
+				source: "eliza-download",
+			},
+		];
+
+		const readiness = buildTextGenerationReadiness({
+			assignments: {
+				TEXT_SMALL: "eliza-1-2b",
+			},
+			installed,
+			active: {
+				modelId: "eliza-1-2b",
+				loadedAt: new Date().toISOString(),
+				status: "ready",
+			},
+			downloads: [],
+		});
+
+		expect(readiness.slots.TEXT_SMALL.downloaded).toBe(true);
+		expect(readiness.slots.TEXT_SMALL.active).toBe(true);
+		expect(readiness.slots.TEXT_SMALL.ready).toBe(true);
+		expect(readiness.slots.TEXT_SMALL.state).toBe("active");
+	});
+});

package/src/services/readiness.ts

@@ -0,0 +1,238 @@
+import { MODEL_CATALOG } from "./catalog";
+import { catalogDownloadSizeBytes } from "./recommendation";
+import type {
+	ActiveModelState,
+	CatalogModel,
+	DownloadJob,
+	DownloadState,
+	InstalledModel,
+	LocalInferenceDownloadStatus,
+	LocalInferenceReadiness,
+	LocalInferenceSlotReadiness,
+	ModelAssignments,
+	TextGenerationSlot,
+} from "./types";
+
+const TERMINAL_STATES = new Set<DownloadState>([
+	"completed",
+	"failed",
+	"cancelled",
+]);
+
+function catalogById(catalog: CatalogModel[]): Map<string, CatalogModel> {
+	return new Map(catalog.map((model) => [model.id, model]));
+}
+
+function installedById(
+	installed: InstalledModel[],
+): Map<string, InstalledModel> {
+	return new Map(installed.map((model) => [model.id, model]));
+}
+
+function latestJobByModel(downloads: DownloadJob[]): Map<string, DownloadJob> {
+	const jobs = new Map<string, DownloadJob>();
+	for (const job of downloads) {
+		const current = jobs.get(job.modelId);
+		if (!current || job.updatedAt.localeCompare(current.updatedAt) > 0) {
+			jobs.set(job.modelId, job);
+		}
+	}
+	return jobs;
+}
+
+function requiredModelIds(
+	assignedModelId: string,
+	catalog: Map<string, CatalogModel>,
+): string[] {
+	const model = catalog.get(assignedModelId);
+	return model ? [assignedModelId] : [assignedModelId];
+}
+
+function statusFromJobs(
+	jobs: DownloadJob[],
+	missingModelIds: string[],
+): LocalInferenceDownloadStatus {
+	const activeJobs = jobs.filter(
+		(job) => job.state === "queued" || job.state === "downloading",
+	);
+	const terminalJobs = jobs.filter((job) => TERMINAL_STATES.has(job.state));
+	const relevantJobs = activeJobs.length > 0 ? activeJobs : terminalJobs;
+	const state =
+		relevantJobs.find((job) => job.state === "failed")?.state ??
+		relevantJobs.find((job) => job.state === "cancelled")?.state ??
+		relevantJobs.find((job) => job.state === "downloading")?.state ??
+		relevantJobs.find((job) => job.state === "queued")?.state ??
+		relevantJobs.find((job) => job.state === "completed")?.state ??
+		(missingModelIds.length > 0 ? "missing" : "completed");
+	const receivedBytes = relevantJobs.reduce(
+		(total, job) => total + job.received,
+		0,
+	);
+	const totalBytes = relevantJobs.reduce((total, job) => total + job.total, 0);
+	const bytesPerSec = activeJobs.reduce(
+		(total, job) => total + job.bytesPerSec,
+		0,
+	);
+	const etaValues = activeJobs
+		.map((job) => job.etaMs)
+		.filter((etaMs): etaMs is number => etaMs !== null);
+	const etaMs =
+		etaValues.length > 0
+			? Math.max(...etaValues)
+			: (relevantJobs[0]?.etaMs ?? null);
+	const updatedAt =
+		relevantJobs
+			.map((job) => job.updatedAt)
+			.sort((left, right) => right.localeCompare(left))[0] ?? null;
+	const errors = relevantJobs.flatMap((job) => (job.error ? [job.error] : []));
+	return {
+		state,
+		receivedBytes,
+		totalBytes,
+		percent:
+			totalBytes > 0
+				? Math.max(
+						0,
+						Math.min(100, Math.round((receivedBytes / totalBytes) * 1000) / 10),
+					)
+				: null,
+		bytesPerSec,
+		etaMs,
+		updatedAt,
+		errors,
+	};
+}
+
+function slotReadiness(
+	slot: TextGenerationSlot,
+	assignments: ModelAssignments,
+	installed: Map<string, InstalledModel>,
+	catalog: Map<string, CatalogModel>,
+	catalogList: CatalogModel[],
+	downloads: Map<string, DownloadJob>,
+	active: ActiveModelState,
+): LocalInferenceSlotReadiness {
+	const assignedModelId = assignments[slot] ?? null;
+	if (!assignedModelId) {
+		return {
+			slot,
+			assigned: false,
+			assignedModelId: null,
+			displayName: null,
+			primaryDownloaded: false,
+			downloaded: false,
+			active: false,
+			ready: false,
+			state: "unassigned",
+			requiredModelIds: [],
+			missingModelIds: [],
+			installedBytes: 0,
+			expectedBytes: 0,
+			download: {
+				state: "missing",
+				receivedBytes: 0,
+				totalBytes: 0,
+				percent: null,
+				bytesPerSec: 0,
+				etaMs: null,
+				updatedAt: null,
+				errors: [],
+			},
+			errors: [],
+		};
+	}
+
+	const ids = requiredModelIds(assignedModelId, catalog);
+	const missingModelIds = ids.filter((id) => !installed.has(id));
+	const primaryDownloaded = installed.has(assignedModelId);
+	const downloaded = missingModelIds.length === 0;
+	const activeReady =
+		active.modelId === assignedModelId && active.status === "ready";
+	const model = catalog.get(assignedModelId);
+	const jobs = ids.flatMap((id) => {
+		const job = downloads.get(id);
+		return job ? [job] : [];
+	});
+	const download = statusFromJobs(jobs, missingModelIds);
+	const activeError =
+		active.modelId === assignedModelId &&
+		active.status === "error" &&
+		active.error
+			? [active.error]
+			: [];
+	const errors = [...download.errors, ...activeError];
+	const hasActiveJob = jobs.some(
+		(job) => job.state === "queued" || job.state === "downloading",
+	);
+	const terminalFailure = jobs.find(
+		(job) => job.state === "failed" || job.state === "cancelled",
+	);
+
+	return {
+		slot,
+		assigned: true,
+		assignedModelId,
+		displayName:
+			model?.displayName ?? installed.get(assignedModelId)?.displayName ?? null,
+		primaryDownloaded,
+		downloaded,
+		active: activeReady,
+		ready: downloaded && activeReady,
+		state: terminalFailure
+			? terminalFailure.state === "failed"
+				? "failed"
+				: "cancelled"
+			: hasActiveJob
+				? "downloading"
+				: activeReady
+					? "active"
+					: downloaded
+						? "downloaded"
+						: "missing",
+		requiredModelIds: ids,
+		missingModelIds,
+		installedBytes: ids.reduce(
+			(total, id) => total + (installed.get(id)?.sizeBytes ?? 0),
+			0,
+		),
+		expectedBytes: model ? catalogDownloadSizeBytes(model, catalogList) : 0,
+		download,
+		errors,
+	};
+}
+
+export function buildTextGenerationReadiness(input: {
+	assignments: ModelAssignments;
+	installed: InstalledModel[];
+	active: ActiveModelState;
+	downloads: DownloadJob[];
+	catalog?: CatalogModel[];
+}): LocalInferenceReadiness {
+	const catalogList = input.catalog ?? MODEL_CATALOG;
+	const catalog = catalogById(catalogList);
+	const installed = installedById(input.installed);
+	const downloads = latestJobByModel(input.downloads);
+	return {
+		updatedAt: new Date().toISOString(),
+		slots: {
+			TEXT_SMALL: slotReadiness(
+				"TEXT_SMALL",
+				input.assignments,
+				installed,
+				catalog,
+				catalogList,
+				downloads,
+				input.active,
+			),
+			TEXT_LARGE: slotReadiness(
+				"TEXT_LARGE",
+				input.assignments,
+				installed,
+				catalog,
+				catalogList,
+				downloads,
+				input.active,
+			),
+		},
+	};
+}

package/src/services/recommendation.d.ts

@@ -0,0 +1,111 @@
+import { type Eliza1DeviceCaps } from "./manifest";
+import { type ManifestLoader } from "./ram-budget";
+import type { CatalogModel, CatalogQuantizationVariant, HardwareFitLevel, HardwareProbe, InstalledModel, TextGenerationSlot } from "./types";
+export type RecommendationPlatformClass = "mobile" | "apple-silicon" | "linux-gpu" | "linux-cpu" | "desktop-gpu" | "desktop-cpu";
+export interface RecommendedModelSelection {
+    slot: TextGenerationSlot;
+    platformClass: RecommendationPlatformClass;
+    model: CatalogModel | null;
+    fit: HardwareFitLevel | null;
+    reason: string;
+    alternatives: CatalogModel[];
+}
+export declare function classifyRecommendationPlatform(hardware: HardwareProbe): RecommendationPlatformClass;
+export declare function catalogDownloadSizeGb(model: CatalogModel, catalog?: CatalogModel[]): number;
+export declare function catalogDownloadSizeBytes(model: CatalogModel, catalog?: CatalogModel[]): number;
+export declare function selectBestQuantizationVariant(model: CatalogModel): CatalogQuantizationVariant | null;
+export declare function assessCatalogModelFit(hardware: HardwareProbe, model: CatalogModel, catalog?: CatalogModel[], options?: {
+    installed?: InstalledModel;
+    manifestLoader?: ManifestLoader;
+}): HardwareFitLevel;
+export interface RecommendationOptions {
+    /**
+     * Kernels actually advertised by the installed llama-server binary
+     * (parsed from CAPABILITIES.json next to it). When provided, models
+     * declaring `requiresKernel` not satisfied by this map are filtered
+     * out so we don't recommend a model the user can't actually run on
+     * this binary. Pass null/omit when no probe is available — recommender
+     * trusts the catalog and the dispatcher's load-time check.
+     */
+    binaryKernels?: Partial<Record<string, boolean>> | null;
+    /**
+     * Models the user has already installed. When an Eliza-1 tier in this
+     * list has a published `eliza-1.manifest.json` next to its bundle,
+     * the recommender consults `manifest.ramBudgetMb` instead of the
+     * catalog's coarse `minRamGb` scalar. See `./ram-budget.ts`.
+     */
+    installed?: ReadonlyArray<InstalledModel>;
+    /**
+     * Test-only override for the manifest reader. Production callers leave
+     * this unset and the helper reads `eliza-1.manifest.json` from disk.
+     */
+    manifestLoader?: ManifestLoader;
+}
+export declare function selectRecommendedModelForSlot(slot: TextGenerationSlot, hardware: HardwareProbe, catalog?: CatalogModel[], options?: RecommendationOptions): RecommendedModelSelection;
+/**
+ * Project a `HardwareProbe` onto the `Eliza1DeviceCaps` shape the manifest
+ * validator's `canSetAsDefault` consumes. CPU is always available; a probed
+ * GPU contributes exactly its one backend (`cuda` / `metal` / `vulkan`). RAM
+ * is the device total, in MB — `canSetAsDefault` compares against the
+ * manifest's `ramBudgetMb.min` floor, not the headroom-discounted figure the
+ * ladder uses, because the floor is "will it boot at all".
+ */
+export declare function deviceCapsFromProbe(hardware: HardwareProbe): Eliza1DeviceCaps;
+export type BundleDefaultEligibility = {
+    canBeDefault: true;
+} | {
+    canBeDefault: false;
+    reason: "no-manifest" | "not-default-eligible" | "ram-below-floor" | "kernels-unverified-on-device" | "not-verified-on-device";
+    detail: string;
+};
+/**
+ * True iff this installed Eliza-1 bundle may be offered as the recommended
+ * default on this device. The full set of conditions (any one failing →
+ * not default):
+ *
+ *  - the bundle ships a validated `eliza-1.manifest.json`,
+ *  - the manifest is contract-valid (every required kernel declared, every
+ *    required eval green for a strict release, lineage/files consistent —
+ *    enforced by `canSetAsDefault` → `collectContractErrors`),
+ *  - the device exposes at least one backend the manifest verified `pass` on
+ *    out of the tier's supported set,
+ *  - the device RAM meets the manifest's `ramBudgetMb.min` floor,
+ *  - the bundle has passed the one-time on-device verify pass
+ *    (`InstalledModel.bundleVerifiedAt` is set) — a materialized-but-unverified
+ *    bundle is never auto-selected, per AGENTS.md §7.
+ *
+ * `manifest.defaultEligible: true` is NOT required at the gate level — a
+ * `base-v1-candidate` bundle that passes every above condition is allowed
+ * to fill an empty default slot. The recommender prefers a strict release
+ * (`defaultEligible: true`) over a candidate when both are installed.
+ */
+export declare function canBundleBeDefaultOnDevice(installed: InstalledModel, hardware: HardwareProbe, options?: {
+    manifestLoader?: ManifestLoader;
+}): BundleDefaultEligibility;
+export declare function selectRecommendedModels(hardware: HardwareProbe, catalog?: CatalogModel[], options?: RecommendationOptions): Record<TextGenerationSlot, RecommendedModelSelection>;
+/**
+ * Pick the model the engine should auto-load on first run when no user
+ * preference exists. Always resolves to an Eliza-1 default-eligible
+ * tier — never a non-Eliza catalog entry, never a HF-search result.
+ *
+ * Resolution order:
+ *   1. `FIRST_RUN_DEFAULT_MODEL_ID` when present in the catalog, in the
+ *      default-eligible set, and not marked `publishStatus: "pending"`.
+ *   2. The first default-eligible, non-pending chat entry in the catalog
+ *      as a fallback when the preferred id is missing or its HF bundle
+ *      isn't published yet (elizaOS/eliza#7629). The fall-through walks
+ *      the catalog in order, so the maintainer can keep
+ *      `FIRST_RUN_DEFAULT_MODEL_ID` pointed at the *intended* default
+ *      while the publish pipeline catches up.
+ *   3. If every default-eligible tier is pending, last-resort to ANY
+ *      default-eligible tier — the device download path will fail
+ *      cleanly with a 404 rather than silently picking a private
+ *      non-Eliza model.
+ *
+ * Returns null only when no default-eligible entry exists at all —
+ * which means the catalog is misconfigured and the caller should
+ * surface a hard error rather than degrade silently.
+ */
+export declare function recommendForFirstRun(catalog?: CatalogModel[]): CatalogModel | null;
+export declare function chooseSmallerFallbackModel(currentModelId: string, hardware: HardwareProbe, slot?: TextGenerationSlot, catalog?: CatalogModel[], options?: RecommendationOptions): CatalogModel | null;
+//# sourceMappingURL=recommendation.d.ts.map

package/src/services/recommendation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendation.d.ts","sourceRoot":"","sources":["recommendation.ts"],"names":[],"mappings":"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"}