@bendyline/gezel-inference 1.0.2 → 1.0.4

package/dist/inference-service.d.ts

@@ -1,4 +1,5 @@
-import { type ProviderName } from '@bendyline/gezel';
+import { type LogOutput, type ProviderName } from '@bendyline/gezel';
+import type { ImageProvider } from './providers/image/types.js';
 import type { LLMProvider } from './providers/types.js';
 import './http/auth-context.js';
 /** Same shape the full service reports, so one handler serves either host. */
@@ -14,7 +15,14 @@ export interface InferenceServiceOptions {
     home?: string;
     /** Host-provided local providers, useful for testing without downloading weights. */
     providers?: ReadonlyMap<ProviderName, LLMProvider>;
+    /** Host-provided image provider in place of the local engine, for tests. */
+    imageProvider?: ImageProvider;
     onUnexpectedHttpError?: (event: InferenceHttpErrorEvent) => void;
+    /**
+     * Where log records go while this host runs; restored on `stop()`. An app
+     * embedding the host passes `'stderr'` so its own stdout stays its own.
+     */
+    logOutput?: LogOutput;
 }
 export interface RunningInferenceService {
     readonly profile: 'embedded-inference';

package/dist/inference-service.js

@@ -1,6 +1,6 @@
 import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
 import { join } from 'node:path';
-import { GEZEL_API_GENERATION, GEZEL_API_GENERATION_FLOOR, GEZEL_VERSION, GezelConfigSchema, createLogger, nowIso, startSuspendMonitor, stopSuspendMonitor, } from '@bendyline/gezel';
+import { GEZEL_API_GENERATION, GEZEL_API_GENERATION_FLOOR, GEZEL_VERSION, GezelConfigSchema, createLogger, getLogOutput, nowIso, setLogOutput, startSuspendMonitor, stopSuspendMonitor, } from '@bendyline/gezel';
 import { BundledSource, CatalogService } from '@bendyline/gezel-catalog';
 import { discoverNativeBinaries } from '@bendyline/gezel/native';
 import { gezelHome } from '@bendyline/gezel/paths';
@@ -14,6 +14,7 @@ import { enginesRoutes } from './http/routes/engines.js';
 import { modelBundleRoutes } from './http/routes/model-bundles.js';
 import { v1ChatRoutes } from './http/routes/v1-chat.js';
 import { v1EmbeddingsRoutes } from './http/routes/v1-embeddings.js';
+import { v1ImagesRoutes } from './http/routes/v1-images.js';
 import { v1KnowledgeRoutes } from './http/routes/v1-knowledge.js';
 import { v1ModelsEnsureRoutes } from './http/routes/v1-models-ensure.js';
 import { v1ModelsRoutes } from './http/routes/v1-models.js';
@@ -23,6 +24,7 @@ import { KnowledgeManager } from './knowledge/manager.js';
 import { createWorkerCatalogHost } from './knowledge/worker-host.js';
 import { embeddingsHealth, openEmbeddings, shutdownEmbeddings } from './memory/embeddings.js';
 import { AppleFoundationModelsProvider } from './providers/apple-foundation-models/provider.js';
+import { LocalImageEngine } from './providers/image/local-engine.js';
 import { EngineInference } from './providers/native/inference.js';
 import { resolveModelSessionDefaults } from './providers/session-defaults.js';
 import { MlxRuntimeStatusBus } from './python/mlx-runtime-status-bus.js';
@@ -35,16 +37,27 @@ import './http/auth-context.js';
 const log = createLogger('inference');
 /** Direct Fetch host: no listener, product store, background downloads or daemon discovery. */
 export async function startService(options = {}) {
+    const previousLogOutput = getLogOutput();
+    const restoreLogOutput = () => setLogOutput(previousLogOutput);
+    if (options.logOutput)
+        setLogOutput(options.logOutput);
     const home = options.home ?? gezelHome();
-    await ensurePrivateUserHome(home);
-    // Model files must land in this home's managed cache: unset, transformers.js
-    // falls back to a module-relative cache that is read-only inside a packaged
-    // app, and the embed worker (which reads this env) has no other view of home.
-    process.env[HF_CACHE_DIR_ENV] ??= transformersCacheDir(home);
-    const startedAt = nowIso();
     const runtimeDir = join(home, 'runtime');
-    const lock = await acquireSingleInstanceLock({ runtimeDir, lockPath: join(runtimeDir, 'lock') });
-    const cleanup = [() => lock.release()];
+    let lock;
+    try {
+        await ensurePrivateUserHome(home);
+        // Model files must land in this home's managed cache: unset, transformers.js
+        // falls back to a module-relative cache that is read-only inside a packaged
+        // app, and the embed worker (which reads this env) has no other view of home.
+        process.env[HF_CACHE_DIR_ENV] ??= transformersCacheDir(home);
+        lock = await acquireSingleInstanceLock({ runtimeDir, lockPath: join(runtimeDir, 'lock') });
+    }
+    catch (error) {
+        restoreLogOutput();
+        throw error;
+    }
+    const startedAt = nowIso();
+    const cleanup = [restoreLogOutput, () => lock.release()];
     const requests = new InFlightRequests();
     let stopping;
     let closed = false;
@@ -146,7 +159,25 @@ export async function startService(options = {}) {
         await knowledge.start();
         const relevance = new RelevanceModelManager({ home, readConfig: () => store.readConfig() });
         cleanup.push(() => relevanceScorer().dispose());
-        const context = { home, store, catalog, chat, knowledge, relevance, ...components };
+        const images = new LocalImageEngine({
+            home,
+            catalog,
+            arbiter: components.gpuArbiter,
+            readConfig: () => store.readConfig(),
+            ...(options.imageProvider ? { provider: options.imageProvider } : {}),
+        });
+        cleanup.push(() => images.shutdown());
+        const context = {
+            home,
+            store,
+            catalog,
+            chat,
+            knowledge,
+            relevance,
+            images,
+            imageProvider: images,
+            ...components,
+        };
         const clientToken = randomBytes(32).toString('base64url');
         const tokenBytes = Buffer.from(clientToken);
         const app = new Hono();
@@ -180,12 +211,13 @@ export async function startService(options = {}) {
             nodeVersion: process.versions.node,
             platform: process.platform,
             embeddings: embeddingsHealth(),
+            images: { available: images.available() },
         }));
         app.use('*', async (c, next) => {
             const candidate = Buffer.from(c.req.header('authorization')?.replace(/^Bearer /, '') ?? '');
             if (candidate.length !== tokenBytes.length || !timingSafeEqual(candidate, tokenBytes))
                 return c.json({ error: 'Unauthorized' }, 401);
-            c.set('auth', { appId: 'host', scopes: ['openai', 'knowledge'] });
+            c.set('auth', { appId: 'host', scopes: ['openai', 'knowledge', 'images'] });
             return next();
         });
         const allowedProviders = ['llama-cpp', 'mlx', 'ds4', 'apple-foundation-models'];
@@ -196,6 +228,7 @@ export async function startService(options = {}) {
         app.route('/v1/models/ensure', v1ModelsEnsureRoutes(context));
         app.route('/v1/models', v1ModelsRoutes(context, { localOnly: true }));
         app.route('/v1/knowledge', v1KnowledgeRoutes(context));
+        app.route('/v1/images', v1ImagesRoutes(context));
         app.route('/api/engines', enginesRoutes(context));
         app.route('/api/model-bundles', modelBundleRoutes(context));
         for (const [engine, manager] of [

package/dist/knowledge/manager.d.ts

@@ -260,6 +260,13 @@ export declare class KnowledgeManager {
          * their own. Explicit search asks; proactive injection does not.
          */
         media?: boolean;
+        /**
+         * Also return up to this many of a document's other passages that the
+         * search found, after its best one. Fusion otherwise keeps one passage
+         * per document, chosen by vector similarity alone, so an article's name-
+         * dense infobox can stand in for the section a reranker would choose.
+         */
+        chunksPerDocument?: number;
     }): Promise<UnifiedSearchResult[]>;
     /** A document the lexical arms named but no chunk carries: cite it with its lead paragraph. */
     private toDocumentResult;

package/dist/knowledge/manager.js

@@ -1315,6 +1315,20 @@ export class KnowledgeManager {
             }
             fused.set(key, entry);
         };
+        // Every text passage the arms found, per document, best vector match first,
+        // for `chunksPerDocument`. Fusion still ranks documents, not passages.
+        const passagesByDocument = new Map();
+        if ((opts.chunksPerDocument ?? 1) > 1) {
+            for (const hit of response.chunks
+                .filter((h) => !h.media)
+                .sort((a, b) => (b.cosine ?? -1) - (a.cosine ?? -1))) {
+                const key = `${hit.catalogKey}\u0000${hit.documentId}`;
+                const passages = passagesByDocument.get(key) ?? [];
+                if (!passages.some((known) => known.chunkUid === hit.chunkUid))
+                    passages.push(hit);
+                passagesByDocument.set(key, passages);
+            }
+        }
         // Vector arm: one rank per document, in rerank-cosine order. A hit under
         // its profile's floor is not evidence at all — KNN always returns its
         // nearest rows, and a rank-0 row fuses to relevance 1.0 however far away
@@ -1446,7 +1460,24 @@ export class KnowledgeManager {
                 continue;
             perCatalogCount.set(entry.catalogKey, count + 1);
             seenSpatial.add(spatialIdentity);
-            out.push({ ...result, ...matches.get(`${entry.catalogKey}\u0000${entry.documentId}`) });
+            const docKey = `${entry.catalogKey}\u0000${entry.documentId}`;
+            out.push({ ...result, ...matches.get(docKey) });
+            if (out.length >= Math.max(10, opts.maxResults))
+                break;
+            // The document's other passages, each labelled by its own evidence: a
+            // sibling is vector evidence only if it clears the floor by itself.
+            const siblings = (passagesByDocument.get(docKey) ?? [])
+                .filter((hit) => hit.chunkUid !== entry.chunk?.chunkUid)
+                .slice(0, Math.max(0, (opts.chunksPerDocument ?? 1) - 1));
+            const floor = this.vectorFloorFor(entry.catalogKey);
+            for (const sibling of siblings) {
+                const own = floor !== null && sibling.cosine !== undefined && sibling.cosine >= floor
+                    ? { arm: 'vector', similarity: sibling.cosine }
+                    : { arm: 'fts' };
+                out.push(this.toResult(info, sibling, fusedRankRelevance(out.length), own));
+                if (out.length >= Math.max(10, opts.maxResults))
+                    break;
+            }
             if (out.length >= Math.max(10, opts.maxResults))
                 break;
         }

package/dist/kokoro-lexicon/manifest.json

@@ -1,8 +1,11 @@
 {
   "source": {
-    "url": "https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/kokoro-int8-multi-lang-v1_0.tar.bz2",
-    "sha256": "4c3052abaa60943a341f193888cf6abd68787dae6ab8ae5c925a706caa247e4e",
-    "file": "kokoro-model.tar.bz2"
+    "url": "https://huggingface.co/csukuangfj/kokoro-int8-multi-lang-v1_0/resolve/57adb37fc0e8d4bd430cfc1b8f8c2294945b9af2/",
+    "files": {
+      "lexicon-us-en.txt": "7daaab53a181be9885b853a8582bf1838186317e5dadacbcef9c426d6fa0da14",
+      "lexicon-gb-en.txt": "c4cbb37316f62210dff52718a7afcaae24f50c032cc75ab47ae67b831d1049e7",
+      "LICENSE": "cfc7749b96f63bd31c3c42b5c471bf756814053e847c10f3eb003417bc523d30"
+    }
   },
   "license": {
     "file": "LICENSE",

package/dist/models/image-fit.d.ts

@@ -0,0 +1,83 @@
+/**
+ * "Can this machine run that image model?" for the image catalog.
+ *
+ * Prices each catalog entry from the weight facts its gilde entry pins (core
+ * `media-memory.ts`) — never the network — and checks it against the same
+ * static ceilings the device ledger refuses at, so `wont-run` here means the
+ * launch path would refuse the model on this machine whatever else is
+ * running. The download pages hide those models and the pull routes refuse
+ * them. Contract: docs/media-model-memory.md.
+ *
+ * The video half lives with the video engine in the service, which shares
+ * the helpers here.
+ */
+import { type GezelConfig, type ImageModelManifest, type ImageQuality, type MediaCapacity, type MediaFitAssessment, type MediaMemoryPool, type MediaMemoryRequirement, type MediaModelFit, type MediaModelFitResponse, type MediaWeightFile } from '@bendyline/gezel';
+import type { CatalogService } from '@bendyline/gezel-catalog';
+import type { CapacityBudgetKind } from '../providers/native/capacity-budget.js';
+export interface MediaFitContext {
+    catalog: CatalogService;
+    readConfig: () => Promise<Pick<GezelConfig, 'localEngineMemoryGb'>>;
+}
+/**
+ * The 409 body a pull route answers with when the model cannot run here, or
+ * null to let the pull start. A failure to assess never blocks a download:
+ * the launch path still applies the same check.
+ */
+export declare function wontRunRefusal(assess: () => Promise<MediaFitAssessment | null>): Promise<{
+    error: string;
+    code: string;
+} | null>;
+/**
+ * Where sd-server keeps weights: Metal on Apple Silicon, CPU on Intel Macs,
+ * CUDA or Vulkan elsewhere, falling back to the processor when no GPU
+ * answers. Windows on Arm runs on the processor unless discovery picked its
+ * CUDA build, which only an RTX Spark gets.
+ */
+export declare function imageMediaPool(kind: CapacityBudgetKind, host?: {
+    platform: NodeJS.Platform;
+    arch: string;
+    sdServerBin?: string | undefined;
+}): MediaMemoryPool;
+/** The ceilings the device ledger applies on this machine, automatic and under the person's limit. */
+export declare function mediaCapacity(pool: MediaMemoryPool, readConfig: MediaFitContext['readConfig']): Promise<MediaCapacity>;
+/** The memory sd-server needs for one model, from its weight files and its launch profile. */
+export declare function sdServerRequirement(input: {
+    modelId: string;
+    weightsKind: 'checkpoint' | 'diffusion-model';
+    files: readonly MediaWeightFile[];
+    pool: MediaMemoryPool;
+    /** The render size to price; the model's default size when absent. */
+    megapixels?: number;
+}): MediaMemoryRequirement;
+/**
+ * What a launched sd-server claims on the device ledger.
+ *
+ * On a discrete card the fit figures charge graphics memory for weights only,
+ * because sd-server can stream components from RAM, and the download page
+ * must not call a model that offloads "won't run". A running render holds its
+ * compute buffers on the card too, though: FLUX.2 Klein at 1024px held
+ * 9.4 GiB of a 12 GiB card's dedicated memory against 4.9 GiB of weights
+ * (RTX 5070 Ti Laptop, Vulkan, M0 spike 2026-10-25). Claiming weights only
+ * let a resident chat model keep its memory, and the render then failed at
+ * its first step. The claim is the estimated peak, capped at the card so a
+ * model that must offload is admitted once the card is otherwise free.
+ */
+export declare function sdServerLedgerClaim(requirement: MediaMemoryRequirement, cardBytes: number): {
+    bytes: number;
+    gpuBytes: number;
+};
+/** Megapixels a model renders at a quality tier, inside its range. */
+export declare function imageRenderMegapixels(manifest: Pick<ImageModelManifest, 'id' | 'widthRange' | 'heightRange'>, quality: ImageQuality): number;
+export interface FitPlan {
+    pool: MediaMemoryPool;
+    capacity: MediaCapacity;
+}
+export declare function mediaFitResponse(plan: FitPlan, models: MediaModelFit[]): MediaModelFitResponse;
+/**
+ * Every catalog image model's fit. With `quality`, each is priced at the size
+ * it renders at that tier rather than its default, which is how the direct
+ * image gezel's settings know whether High will fit.
+ */
+export declare function imageCatalogFits(ctx: MediaFitContext, quality?: ImageQuality): Promise<MediaModelFitResponse>;
+/** One catalog image model's fit, or null when the id is not in the catalog. */
+export declare function imageModelFit(ctx: MediaFitContext, id: string): Promise<MediaFitAssessment | null>;

package/dist/models/image-fit.js

@@ -0,0 +1,163 @@
+/**
+ * "Can this machine run that image model?" for the image catalog.
+ *
+ * Prices each catalog entry from the weight facts its gilde entry pins (core
+ * `media-memory.ts`) — never the network — and checks it against the same
+ * static ceilings the device ledger refuses at, so `wont-run` here means the
+ * launch path would refuse the model on this machine whatever else is
+ * running. The download pages hide those models and the pull routes refuse
+ * them. Contract: docs/media-model-memory.md.
+ *
+ * The video half lives with the video engine in the service, which shares
+ * the helpers here.
+ */
+import { totalmem } from 'node:os';
+import { MEDIA_MODEL_WONT_RUN_CODE, assessMediaFit, createLogger, imageMemoryRequirement, imageModelDefaultSide, resolveImageSize, } from '@bendyline/gezel';
+import { isCudaArchivePath } from '@bendyline/gezel/native';
+import { sdServerLoadProfile } from '../providers/image/sd-cpp.js';
+import { configuredEngineMemoryBytes, staticCapacityCeilings, } from '../providers/native/device-capacity.js';
+import { measuredCapacityBudget } from '../providers/native/measured-budget.js';
+import { detectMemoryProfileCached } from '../system/memory.js';
+import { imageCatalogWeightFiles, sdCppMainComponent } from './weight-facts.js';
+const log = createLogger('media-fit');
+/**
+ * The 409 body a pull route answers with when the model cannot run here, or
+ * null to let the pull start. A failure to assess never blocks a download:
+ * the launch path still applies the same check.
+ */
+export async function wontRunRefusal(assess) {
+    try {
+        const fit = await assess();
+        if (fit?.verdict !== 'wont-run')
+            return null;
+        return {
+            error: `This model is too large for this machine. ${fit.reason}`,
+            code: MEDIA_MODEL_WONT_RUN_CODE,
+        };
+    }
+    catch (error) {
+        log.warn(`[media-fit] could not assess a pull, letting it start: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+/**
+ * Where sd-server keeps weights: Metal on Apple Silicon, CPU on Intel Macs,
+ * CUDA or Vulkan elsewhere, falling back to the processor when no GPU
+ * answers. Windows on Arm runs on the processor unless discovery picked its
+ * CUDA build, which only an RTX Spark gets.
+ */
+export function imageMediaPool(kind, host = {
+    platform: process.platform,
+    arch: process.arch,
+    sdServerBin: process.env.GEZEL_SD_SERVER_BIN,
+}) {
+    if (host.platform === 'darwin')
+        return host.arch === 'arm64' ? 'unified' : 'cpu';
+    if (host.platform === 'win32' &&
+        host.arch === 'arm64' &&
+        !(host.sdServerBin && isCudaArchivePath(host.sdServerBin))) {
+        return 'cpu';
+    }
+    return kind === 'discrete-gpu' ? 'discrete' : kind === 'unified' ? 'unified' : 'cpu';
+}
+/** The ceilings the device ledger applies on this machine, automatic and under the person's limit. */
+export async function mediaCapacity(pool, readConfig) {
+    const budget = await measuredCapacityBudget();
+    const ram = totalmem();
+    const auto = staticCapacityCeilings(budget, ram);
+    const configured = configuredEngineMemoryBytes(await readConfig().catch(() => ({})));
+    const limited = configured === undefined ? undefined : staticCapacityCeilings(budget, ram, configured);
+    const profile = pool === 'discrete' ? await detectMemoryProfileCached().catch(() => null) : null;
+    return {
+        pool,
+        ...auto,
+        ...(limited && limited.budgetBytes < auto.budgetBytes ? { limit: limited } : {}),
+        totalRamBytes: ram,
+        ...(profile?.gpuLargestDeviceBytes ? { gpuDeviceBytes: profile.gpuLargestDeviceBytes } : {}),
+    };
+}
+/** The memory sd-server needs for one model, from its weight files and its launch profile. */
+export function sdServerRequirement(input) {
+    const profile = sdServerLoadProfile(input.modelId);
+    return imageMemoryRequirement({
+        files: input.files,
+        pool: input.pool,
+        vaeDecode: profile.vaeDecode,
+        // The rule names the diffusion weights, which are the main file.
+        bf16Components: profile.bf16TensorPattern ? [sdCppMainComponent(input.weightsKind)] : [],
+        megapixels: input.megapixels ?? profile.defaultSidePx ** 2 / 1024 ** 2,
+    });
+}
+/**
+ * What a launched sd-server claims on the device ledger.
+ *
+ * On a discrete card the fit figures charge graphics memory for weights only,
+ * because sd-server can stream components from RAM, and the download page
+ * must not call a model that offloads "won't run". A running render holds its
+ * compute buffers on the card too, though: FLUX.2 Klein at 1024px held
+ * 9.4 GiB of a 12 GiB card's dedicated memory against 4.9 GiB of weights
+ * (RTX 5070 Ti Laptop, Vulkan, M0 spike 2026-10-25). Claiming weights only
+ * let a resident chat model keep its memory, and the render then failed at
+ * its first step. The claim is the estimated peak, capped at the card so a
+ * model that must offload is admitted once the card is otherwise free.
+ */
+export function sdServerLedgerClaim(requirement, cardBytes) {
+    if (requirement.pool !== 'discrete') {
+        return { bytes: requirement.bytes, gpuBytes: requirement.gpuBytes };
+    }
+    const gpuBytes = Math.min(Math.max(requirement.gpuPeakBytes, requirement.gpuBytes), cardBytes);
+    return { bytes: Math.max(requirement.bytes, gpuBytes), gpuBytes };
+}
+/** Megapixels a model renders at a quality tier, inside its range. */
+export function imageRenderMegapixels(manifest, quality) {
+    const { width, height } = resolveImageSize({ quality }, {
+        defaultSidePx: imageModelDefaultSide(manifest.id),
+        widthRange: manifest.widthRange,
+        heightRange: manifest.heightRange,
+    });
+    return (width * height) / 1024 ** 2;
+}
+async function imagePlan(ctx) {
+    const budget = await measuredCapacityBudget();
+    const pool = imageMediaPool(budget.kind);
+    return { pool, capacity: await mediaCapacity(pool, ctx.readConfig) };
+}
+function assessImageManifest(plan, manifest, quality) {
+    return assessMediaFit(sdServerRequirement({
+        modelId: manifest.id,
+        weightsKind: manifest.weightsKind,
+        files: imageCatalogWeightFiles(manifest),
+        pool: plan.pool,
+        ...(quality ? { megapixels: imageRenderMegapixels(manifest, quality) } : {}),
+    }), plan.capacity);
+}
+export function mediaFitResponse(plan, models) {
+    return {
+        pool: plan.pool,
+        budgetBytes: plan.capacity.budgetBytes,
+        gpuBudgetBytes: plan.capacity.gpuBudgetBytes,
+        totalRamBytes: plan.capacity.totalRamBytes,
+        models,
+    };
+}
+/**
+ * Every catalog image model's fit. With `quality`, each is priced at the size
+ * it renders at that tier rather than its default, which is how the direct
+ * image gezel's settings know whether High will fit.
+ */
+export async function imageCatalogFits(ctx, quality) {
+    const plan = await imagePlan(ctx);
+    const items = await ctx.catalog.list('image-model');
+    const models = items
+        .map((item) => item.manifest)
+        .filter((m) => m.kind === 'image-model')
+        .map((m) => ({ id: m.id, ...assessImageManifest(plan, m, quality) }));
+    return mediaFitResponse(plan, models);
+}
+/** One catalog image model's fit, or null when the id is not in the catalog. */
+export async function imageModelFit(ctx, id) {
+    const item = await ctx.catalog.get('image-model', id);
+    if (!item || item.manifest.kind !== 'image-model')
+        return null;
+    return assessImageManifest(await imagePlan(ctx), item.manifest);
+}

package/dist/models/weight-facts.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Weight facts for media-model memory pricing: each weight file's size and
+ * how many elements it stores at every precision. Core `media-memory.ts`
+ * turns them into a requirement.
+ *
+ * Two sources that must agree. A catalog entry carries the facts as
+ * `tensors` beside each file's sha256, written by gilde's `pin-weight-tensors`
+ * tool when the model was authored; the launch path reads the same facts
+ * from the header of the file on disk. Files are pinned by sha256, so both
+ * describe the same bytes. Nothing here touches the network: an entry
+ * without the facts is priced by its plausible range instead.
+ */
+import { type ImageModelManifest, type MediaWeightFile, type VideoModelManifest, type WeightTensors } from '@bendyline/gezel';
+/** Length of the JSON header from a safetensors file's first 8 bytes, or null when implausible. */
+export declare function safetensorsHeaderLength(prefix: Uint8Array, fileBytes: number): number | null;
+/** The `tensors` facts of a safetensors file on disk; undefined when it cannot be read as one. */
+export declare function readLocalWeightTensors(path: string): Promise<WeightTensors | undefined>;
+export declare function videoCatalogWeightFiles(manifest: VideoModelManifest): MediaWeightFile[];
+/**
+ * The weight files of an installed diffusers tree, headers read from disk.
+ * diffusers loads only the shards a directory's index names, so an unsharded
+ * duplicate beside them is never resident and is left out.
+ */
+export declare function localDiffusersWeightFiles(modelDir: string): Promise<MediaWeightFile[]>;
+/** The sd-cpp component the main weights load as: the flag they ride on. */
+export declare function sdCppMainComponent(weightsKind: 'checkpoint' | 'diffusion-model'): string;
+export declare function imageCatalogWeightFiles(manifest: ImageModelManifest): MediaWeightFile[];
+/** The weight files of an installed sd-cpp model, headers read from disk. */
+export declare function localSdCppWeightFiles(model: {
+    weightsPath: string;
+    weightsKind: 'checkpoint' | 'diffusion-model';
+    auxiliaryFiles: ReadonlyArray<{
+        role: string;
+        path: string;
+    }>;
+}): Promise<MediaWeightFile[]>;

package/dist/models/weight-facts.js

@@ -0,0 +1,171 @@
+/**
+ * Weight facts for media-model memory pricing: each weight file's size and
+ * how many elements it stores at every precision. Core `media-memory.ts`
+ * turns them into a requirement.
+ *
+ * Two sources that must agree. A catalog entry carries the facts as
+ * `tensors` beside each file's sha256, written by gilde's `pin-weight-tensors`
+ * tool when the model was authored; the launch path reads the same facts
+ * from the header of the file on disk. Files are pinned by sha256, so both
+ * describe the same bytes. Nothing here touches the network: an entry
+ * without the facts is priced by its plausible range instead.
+ */
+import { open, readFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tallySafetensorsHeader, weightFileFormat, } from '@bendyline/gezel';
+/** A header larger than this is not a safetensors header. */
+const MAX_HEADER_BYTES = 100 * 1024 * 1024;
+/** Length of the JSON header from a safetensors file's first 8 bytes, or null when implausible. */
+export function safetensorsHeaderLength(prefix, fileBytes) {
+    if (prefix.byteLength < 8)
+        return null;
+    const view = new DataView(prefix.buffer, prefix.byteOffset, 8);
+    const length = Number(view.getBigUint64(0, true));
+    if (!Number.isSafeInteger(length) || length <= 0 || length > MAX_HEADER_BYTES)
+        return null;
+    if (length + 8 > fileBytes)
+        return null;
+    return length;
+}
+/** The `tensors` facts of a safetensors file on disk; undefined when it cannot be read as one. */
+export async function readLocalWeightTensors(path) {
+    let handle;
+    try {
+        handle = await open(path, 'r');
+        const size = (await handle.stat()).size;
+        const prefix = Buffer.alloc(8);
+        const { bytesRead } = await handle.read(prefix, 0, 8, 0);
+        const length = safetensorsHeaderLength(prefix.subarray(0, bytesRead), size);
+        if (length === null)
+            return undefined;
+        const header = Buffer.alloc(length);
+        await handle.read(header, 0, length, 8);
+        return tallySafetensorsHeader(JSON.parse(header.toString('utf8')));
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+function catalogFile(component, fileName, sizeBytes, tensors) {
+    const format = weightFileFormat(fileName);
+    if (!format)
+        return null;
+    return { component, sizeBytes, format, ...(tensors ? { tensors } : {}) };
+}
+// ─ Video: diffusers trees ───────────────────────────────────────────
+/** The diffusers component a repo-relative file belongs to: its top-level folder. */
+function diffusersComponent(name) {
+    const slash = name.indexOf('/');
+    return slash < 0 ? '' : name.slice(0, slash);
+}
+export function videoCatalogWeightFiles(manifest) {
+    return manifest.source.files.flatMap((file) => {
+        const priced = catalogFile(diffusersComponent(file.name), file.name, file.sizeBytes, file.tensors);
+        return priced ? [priced] : [];
+    });
+}
+/**
+ * The weight files of an installed diffusers tree, headers read from disk.
+ * diffusers loads only the shards a directory's index names, so an unsharded
+ * duplicate beside them is never resident and is left out.
+ */
+export async function localDiffusersWeightFiles(modelDir) {
+    const out = [];
+    const walk = async (dir, component, depth) => {
+        if (depth > 6)
+            return;
+        const entries = await readdir(dir, { withFileTypes: true });
+        const indexed = await indexedShards(dir, entries.map((e) => e.name));
+        for (const entry of entries) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(path, component || entry.name, depth + 1);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const format = weightFileFormat(entry.name);
+            if (!format)
+                continue;
+            if (format === 'safetensors' && indexed && !indexed.has(entry.name))
+                continue;
+            const sizeBytes = (await stat(path)).size;
+            const tensors = format === 'safetensors' ? await readLocalWeightTensors(path) : undefined;
+            out.push({ component, sizeBytes, format, ...(tensors ? { tensors } : {}) });
+        }
+    };
+    await walk(modelDir, '', 0);
+    return out;
+}
+async function indexedShards(dir, names) {
+    const index = names.find((n) => n.endsWith('.safetensors.index.json'));
+    if (!index)
+        return null;
+    try {
+        const parsed = JSON.parse(await readFile(join(dir, index), 'utf8'));
+        const shards = new Set(Object.values(parsed.weight_map ?? {}));
+        return shards.size > 0 ? shards : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ─ Image: stable-diffusion.cpp files ────────────────────────────────
+/** The sd-cpp component the main weights load as: the flag they ride on. */
+export function sdCppMainComponent(weightsKind) {
+    return weightsKind === 'diffusion-model' ? 'diffusion_model' : 'model';
+}
+function urlFileName(url) {
+    try {
+        return decodeURIComponent(new URL(url).pathname.split('/').pop() ?? '');
+    }
+    catch {
+        return '';
+    }
+}
+export function imageCatalogWeightFiles(manifest) {
+    const entries = [
+        {
+            component: sdCppMainComponent(manifest.weightsKind),
+            url: manifest.downloadUrl,
+            sizeBytes: manifest.approxSizeBytes,
+            tensors: manifest.tensors,
+        },
+        ...manifest.auxiliaryFiles.map((aux) => ({
+            component: aux.role,
+            url: aux.downloadUrl,
+            sizeBytes: aux.approxSizeBytes,
+            tensors: aux.tensors,
+        })),
+    ];
+    return entries.flatMap((e) => {
+        const priced = catalogFile(e.component, urlFileName(e.url), e.sizeBytes, e.tensors);
+        return priced ? [priced] : [];
+    });
+}
+/** The weight files of an installed sd-cpp model, headers read from disk. */
+export async function localSdCppWeightFiles(model) {
+    const entries = [
+        { component: sdCppMainComponent(model.weightsKind), path: model.weightsPath },
+        ...model.auxiliaryFiles.map((a) => ({ component: a.role, path: a.path })),
+    ];
+    const out = [];
+    for (const entry of entries) {
+        const format = weightFileFormat(entry.path);
+        if (!format)
+            continue;
+        let sizeBytes;
+        try {
+            sizeBytes = (await stat(entry.path)).size;
+        }
+        catch {
+            continue;
+        }
+        const tensors = format === 'safetensors' ? await readLocalWeightTensors(entry.path) : undefined;
+        out.push({ component: entry.component, sizeBytes, format, ...(tensors ? { tensors } : {}) });
+    }
+    return out;
+}