@bendyline/gezel-inference 0.0.0-stage → 0.1.0

package/dist/providers/mlx/models.d.ts

@@ -0,0 +1,289 @@
+/**
+ * MLX model storage + install pipeline.
+ *
+ * Storage layout:
+ *
+ *   <home>/engines/mlx/
+ *   └── models/
+ *       └── <model-id>/
+ *           ├── manifest.json                    (our install record)
+ *           ├── config.json                      (HF model config)
+ *           ├── tokenizer.json
+ *           ├── tokenizer_config.json
+ *           ├── model.safetensors (or sharded model-*.safetensors)
+ *           └── model.safetensors.index.json     (if sharded)
+ *
+ * Install flow (mirrors LlamaCppModelManager.install):
+ *   1. Look up the chat-model in the catalog; require an `mlx` source
+ *      block with a file list + per-file sha256.
+ *   2. For each file, stream-download from
+ *      `huggingface.co/<repo>/resolve/<revision>/<name>` (the pinned
+ *      commit SHA, or `main` for legacy manifests) to a `.partial`
+ *      sibling, hashing as we go.
+ *   3. Verify each file's sha256 against the manifest pin.
+ *   4. Read `config.json` / `tokenizer_config.json` to extract
+ *      contextWindow + chat-template presence.
+ *   5. Atomically rename `.partial` files into place + write
+ *      `manifest.json`.
+ *   6. Yield a terminal `done` or `error` event.
+ *
+ * Delete + resolve flows are identical in shape to the llama-cpp
+ * manager — "first installed, alphabetical" is the default until a
+ * proper picker UI lands.
+ */
+import type { CatalogService } from '@bendyline/gezel-catalog';
+import { type ModelBundleSource } from '../../models/bundle-storage.js';
+import { type ModelUpdateStatus } from '../../models/catalog-drift.js';
+import { type IncompleteModelDownloadInfo, type UnrecognizedModelInfo } from '../../models/storage-roots.js';
+export interface InstalledMlxModel {
+    id: string;
+    name: string;
+    approxSizeBytes: number;
+    /** Cataloged fixed working set with KV excluded; measured values beat the fallback formula. */
+    residentBytes?: number;
+    installedAt: string;
+    /** Absolute path to the model directory the supervisor passes to `mlx_lm.server --model`. */
+    modelDir: string;
+    /** Detected context window (from config.json) or from catalog manifest. */
+    contextWindow?: number;
+    /** Quantization tag (`4bit`, `8bit`, `bf16`) from the catalog source block. */
+    quantization?: string;
+    /** Empty when `tokenizer_config.json` has no `chat_template`. */
+    chatTemplatePresent: boolean;
+    /** Architecture name (`gemma`, `llama`, …) from `config.json#architectures`. */
+    architecture?: string;
+    /**
+     * Catalog manifest `version` as of install. Compared against the
+     * live catalog's version in the UI to surface an "out of date,
+     * reinstall" affordance when a catalog bump changes the upstream
+     * repo, the file list, or the sha256 pins (so a user's stale
+     * install isn't silently pointed at weights that don't match what
+     * the catalog now describes).
+     */
+    catalogVersion?: string;
+    /**
+     * True when this model resolves from a read-only overlay (the machine/shared
+     * asset store) rather than this daemon's writable root. `delete` refuses
+     * these, so the UI shows them as machine-provided rather than offering a
+     * Delete that can only fail.
+     */
+    readOnly?: boolean;
+    /**
+     * True when the catalog now describes a different PAYLOAD than the one on
+     * disk — different repo, file list, or hashes. A version bump that only
+     * edits metadata (tuning, sizing hints, wording) deliberately does not set
+     * this: the runtime resolves that live from the catalog, so there is nothing
+     * for the user to download. Computed server-side in
+     * {@link MlxModelManager.listInstalled} so every surface agrees.
+     */
+    updateAvailable?: boolean;
+    /** The catalog's current version, when it differs from the installed one. */
+    availableVersion?: string;
+    /** What changed, in one sentence, for the model manager's tooltip. */
+    updateReason?: string;
+}
+/**
+ * Snapshot of an in-flight MLX install — same shape as
+ * `LlamaCppActiveInstallSnapshot` so the catalog UI can render
+ * progress for either provider with the same component. MLX
+ * downloads multiple files per install; cumulative bytes drive the
+ * progress bar (one bar per model, not per file).
+ */
+export interface MlxActiveInstallSnapshot {
+    catalogId: string;
+    bytesWritten: number;
+    totalBytes: number;
+    phase: 'downloading' | 'verifying' | 'extracting-metadata';
+    startedAt: string;
+}
+export type MlxInstallEvent = {
+    type: 'progress';
+    fileIndex: number;
+    fileCount: number;
+    file: string;
+    bytesWritten: number;
+    totalBytes: number;
+    /** Cumulative bytes downloaded across every file so far in this
+     *  install (sum of completed files' sizes + current file's
+     *  `bytesWritten`). Lets the UI render one progress bar against
+     *  the whole model instead of per-shard. */
+    bytesWrittenAll: number;
+    /** Sum of `sizeBytes` across every file the manifest pins. Stable
+     *  for the duration of the install. */
+    totalBytesAll: number;
+}
+/**
+ * Surfaced when the shared `downloadWithRetry` helper hit a transient
+ * network error and is about to try again. UI shows
+ * "Connection dropped — retrying in 4s (attempt 3/5)…" The shape
+ * mirrors llama-cpp / sd-cpp; the additional `file` field is for
+ * multi-file MLX models so the UI can show "retrying file 2 of 5".
+ */
+ | {
+    type: 'retrying';
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    reason: string;
+    file: string;
+} | {
+    type: 'verifying';
+    file: string;
+} | {
+    type: 'extracting-metadata';
+} | {
+    type: 'done';
+    id: string;
+    warning?: string;
+}
+/**
+ * Terminal failure. When the failure is specifically a sha256 mismatch
+ * against the catalog's pinned hashes, `mismatch` carries the offending
+ * file + expected/actual so the UI can surface an actionable
+ * "Hugging Face version changed — download anyway?" prompt instead of
+ * a raw error message. The user's "anyway" retry passes
+ * `?skipSha=1` and bypasses verification for that one install.
+ */
+ | {
+    type: 'error';
+    error: string;
+    mismatch?: {
+        file: string;
+        expected: string;
+        actual: string;
+    };
+};
+export interface MlxModelManagerOptions {
+    home: string;
+    catalog: CatalogService;
+    /**
+     * Fire-and-forget hook invoked when a validated, non-duplicate MLX
+     * download is about to start. The service uses it to provision the
+     * shared Python/MLX runtime in parallel with the much larger weights
+     * download, regardless of which HTTP install surface initiated it.
+     */
+    onInstallStart?: (info: {
+        catalogId: string;
+    }) => void;
+    /**
+     * Fire-and-forget hook invoked once a model is fully installed and
+     * readable on disk. The service uses it to queue the post-install
+     * fitness probe (the proeve), mirroring the llama.cpp manager.
+     */
+    onInstalled?: (info: {
+        engine: 'mlx';
+        id: string;
+    }) => void;
+    /** Test seam. */
+    fetchImpl?: typeof fetch;
+}
+export declare class MlxModelManager {
+    private readonly modelsRoot;
+    private readonly viewsRoot;
+    private readonly storageRoots;
+    private readonly catalog;
+    private readonly fetchImpl;
+    private readonly onInstallStart?;
+    private readonly onInstalled?;
+    /**
+     * In-flight installs. See {@link LlamaCppModelManager.activeInstalls}
+     * — same rationale, same shape: the first-run bootstrap fires
+     * `install()` server-side and the Settings catalog UI needs a
+     * polled view of it.
+     */
+    private readonly activeInstalls;
+    /**
+     * Model directories we've already warned about skipping. `listInstalled`
+     * runs on every picker/settings poll; a broken directory should be loud
+     * exactly once per process, not once per poll.
+     */
+    private readonly skipWarned;
+    constructor(opts: MlxModelManagerOptions);
+    getActiveInstalls(): MlxActiveInstallSnapshot[];
+    listInstalled(): Promise<InstalledMlxModel[]>;
+    /**
+     * Whether a genuinely newer build of one installed model exists. Null when
+     * the id isn't installed for MLX. Shared with the chat manager's
+     * per-session staleness notice so a user is never told to re-download for a
+     * change that only touched metadata.
+     */
+    getUpdateStatus(id: string): Promise<ModelUpdateStatus | null>;
+    /**
+     * Compare one installed copy against the live catalog. The catalog lookup
+     * runs for every model on every inventory poll; the manifest re-read only
+     * happens for the few whose version actually moved.
+     */
+    private evaluateDrift;
+    /**
+     * List incomplete MLX downloads — directories that hold bytes but no
+     * `manifest.json`, so they never surface in {@link listInstalled}. Tagged
+     * `resumable` when the id still resolves to an MLX-capable catalog entry.
+     * In-flight installs are excluded. See {@link LlamaCppModelManager.listIncomplete}.
+     */
+    listIncomplete(): Promise<IncompleteModelDownloadInfo[]>;
+    /** Management-only inventory for MLX directories whose manifest exists
+     * but no longer matches the current installed-manifest contract. */
+    listUnrecognized(): Promise<UnrecognizedModelInfo[]>;
+    resolveDefaultModel(): Promise<InstalledMlxModel | null>;
+    resolveDefaultModelPath(): Promise<string | null>;
+    resolveModel(id: string): Promise<InstalledMlxModel | null>;
+    resolveModelPath(id: string): Promise<string | null>;
+    delete(id: string): Promise<void>;
+    /** Provider-owned snapshot used by the streaming `.gezmodel` exporter. */
+    getModelBundleSource(id: string): Promise<ModelBundleSource>;
+    /** Publish a fully-scanned MLX model directory into the provider store. */
+    importModelBundle(opts: {
+        id: string;
+        stagedModelDir: string;
+        installedManifest: Record<string, unknown>;
+        replace: boolean;
+    }): Promise<void>;
+    /**
+     * Install from the catalog. Yields progress events per file; emits
+     * exactly one terminal event. Existing models at `id` are atomically
+     * replaced — files download to `.partial` siblings and rename only
+     * after sha256 verification, same as llama-cpp.
+     */
+    install(catalogId: string, options?: {
+        skipSha?: boolean;
+    }): AsyncIterable<MlxInstallEvent>;
+    /**
+     * Download + verify one file, pushing progress/retrying/verifying/
+     * error events through `push` rather than yielding (so it can run
+     * concurrently with sibling files inside `install`'s worker pool).
+     *
+     * Returns:
+     *   - `'ok'`     — downloaded and sha256-verified (or skipSha bypass).
+     *   - `'error'`  — download or verify failed; a terminal `error` event
+     *                  has already been pushed.
+     *   - `'aborted'`— the shared AbortController fired (a sibling file
+     *                  failed); no terminal event pushed, the failing
+     *                  worker owns the error.
+     */
+    /**
+     * Install a model's speculative-decoding drafter beside it, if the catalog
+     * declares one.
+     *
+     * Deliberately best-effort and deliberately AFTER the model commits: a
+     * drafter only makes decoding faster — every token it proposes is verified
+     * against the target model — so failing to fetch it must leave a working
+     * install rather than failing one. On any error the model serves normally
+     * and the launcher logs `speculative decoding off — no drafter at <path>`.
+     *
+     * Lands at `engines/mlx/drafters/<catalogId>-mtp`, the path
+     * `resolveSpecDrafter` reads, so installing IS enabling.
+     */
+    private installDrafter;
+    private downloadFileConcurrent;
+    /**
+     * Files the plan asks for that are already on disk as exactly the bytes the
+     * catalog pins, keyed by filename with the digest to carry forward. See
+     * {@link LlamaCppModelManager.planReusableFiles} — same trust model: a
+     * digest this install recorded after verifying it, plus a file still at its
+     * pinned length, is identity.
+     */
+    private planReusableFiles;
+    /** Warn once per model directory per process, then stay quiet. */
+    private warnSkip;
+    private loadInstalled;
+}