@bendyline/gezel-inference 1.0.6 → 1.0.8

package/dist/knowledge/unified-search.js

@@ -0,0 +1,373 @@
+/**
+ * Explicit knowledge search across mounted catalogs: each catalog searched in
+ * its own embedding space, the lexical and vector arms fused by reciprocal
+ * rank. Platform-neutral — the daemon's KnowledgeManager and the on-device
+ * Capacitor host both run it over their own KnowledgeCatalogHost.
+ */
+import { formatKnowledgeUri, scoreResult, } from '@bendyline/gezel';
+import { spatialDocumentIdentity } from './spatial-query.js';
+/** Explicit-search shard budget (S) across every active catalog (§3.4). */
+const ROUTE_BUDGET_EXPLICIT = 6;
+/**
+ * Shards added beyond that budget for pages the query names by title (the
+ * catalog host's title-assisted routing): the centroids alone left the ABBA
+ * article unscanned for "Who were the members of ABBA?". Two, not one per
+ * catalog, so twenty mounted catalogs cannot add twenty scans.
+ */
+const TITLE_ROUTE_EXPLICIT = 2;
+const FINAL_K = 24;
+/**
+ * Explicit search fuses three arms per catalog by reciprocal rank (k = 60):
+ * the vector chunks (best chunk per document, by rerank cosine), the
+ * doc-title FTS hits, and the chunk-body FTS hits. Rank fusion instead of
+ * score comparison because the arms' scores are not commensurable — e5
+ * cosines sit in a narrow 0.7–0.9 band for everything, so a cosine-first
+ * ordering buried an exact title match under any vaguely related passage
+ * ("Who painted the Mona Lisa?" listed three other Mona Lisa copies above
+ * the article whose title the question names). Two lexical arms agreeing
+ * on a document now outrank one vector arm; a document every arm names
+ * comes first.
+ */
+const RRF_K = 60;
+const ARM_WEIGHTS = { vector: 1, docFts: 1, chunkFts: 0.5 };
+/**
+ * Media rows fuse per row, not per document: a document's own text chunk
+ * (cosine ≈ 0.9) would otherwise always stand in for its image (≈ 0.7). Each
+ * modality is ranked on its own scale, past its own measured floor.
+ */
+const MEDIA_ARM_WEIGHTS = { vector: 0.5, chunkFts: 0.25 };
+/** Media rows asked of each catalog, per modality, on an explicit search. */
+const MEDIA_K = 2;
+/** Media results one search returns at most, and per document. */
+const MEDIA_RESULT_CAP = 4;
+const MEDIA_PER_DOCUMENT = 1;
+/**
+ * Fused documents per catalog when several are in scope: keeps one catalog
+ * from monopolizing the merged list. A search scoped to one catalog has
+ * nothing to share the list with, and the cap cut the Knowledge browser's
+ * search for "blob" in an Azure-docs catalog — 348 matching titles — to six.
+ */
+const PER_CATALOG_CAP = 6;
+/** Lexical candidates fetched per arm before fusion, at the least. */
+const DOC_FTS_MIN = 6;
+const CHUNK_FTS_MIN = 8;
+/** Rank-anchored relevance for a fused knowledge result: the best hit is a strong 1.0, decaying RRF-style. */
+function fusedRankRelevance(rank) {
+    return 11 / (11 + rank);
+}
+/**
+ * The first prose paragraph of a document body, for a hit that no chunk
+ * carries (a title-only match): the model gets something to read, not just
+ * a summary line. Skips the title heading and a key-facts list.
+ */
+function leadExcerpt(markdown, max = 600) {
+    const body = markdown.replace(/^#\s[^\n]*\n+/, '');
+    const paragraph = body
+        .split(/\n\s*\n/)
+        .map((part) => part.trim())
+        .find((part) => part.length > 0 && !part.startsWith('#') && !part.startsWith('- ')) ??
+        body.trim();
+    return paragraph.length > max ? `${paragraph.slice(0, max - 1)}…` : paragraph;
+}
+export async function searchUnifiedCatalogs(deps, active, query, opts) {
+    if (active.length === 0)
+        return [];
+    const groups = [];
+    const shared = [];
+    const keyword = [];
+    const byProfile = new Map();
+    for (const key of active) {
+        const info = deps.catalog(key);
+        if (!info)
+            continue;
+        if (info.semanticSearch === 'shared' && !opts.localModelsOnly)
+            shared.push(key);
+        else if (info.semanticSearch === 'profile' || info.semanticSearch === 'shared') {
+            const group = byProfile.get(info.embedding.id) ?? { profile: info.embedding, keys: [] };
+            group.keys.push(key);
+            byProfile.set(info.embedding.id, group);
+        }
+        else
+            keyword.push(key);
+    }
+    if (shared.length > 0) {
+        groups.push({
+            keys: shared,
+            ...(opts.vector ? { vector: Float32Array.from(opts.vector) } : {}),
+        });
+    }
+    for (const group of byProfile.values()) {
+        const vector = await deps.embedForProfile(query, group.profile, opts.queryEmbedBudgetMs, opts.localModelsOnly);
+        groups.push({ keys: group.keys, ...(vector ? { vector } : {}) });
+    }
+    if (keyword.length > 0)
+        groups.push({ keys: keyword });
+    const response = {
+        chunks: [],
+        documents: [],
+    };
+    for (const group of groups) {
+        const request = {
+            query,
+            shardBudget: ROUTE_BUDGET_EXPLICIT,
+            titleRouteShards: TITLE_ROUTE_EXPLICIT,
+            finalK: FINAL_K,
+            includeChunkFts: true,
+            catalogKeys: group.keys,
+            // A pool no deeper than the page asked for: six title hits could
+            // never fill a twenty-result browse search.
+            docFtsLimit: Math.max(DOC_FTS_MIN, opts.maxResults),
+            chunkFtsLimit: Math.max(CHUNK_FTS_MIN, opts.maxResults),
+            spatial: opts.spatial,
+        };
+        let part;
+        try {
+            part = await deps.host.search(group.vector
+                ? { ...request, vector: group.vector, ...(opts.media ? { mediaK: MEDIA_K } : {}) }
+                : request);
+        }
+        catch (error) {
+            // A catalog that refuses the query vector (a width the catalog does
+            // not store, say) is an embedding failure, not a search failure: the
+            // worker forwards only the message, so any vector-arm error falls
+            // back to the keyword arms for this group.
+            if (!group.vector)
+                throw error;
+            deps.warn(`[knowledge] semantic search failed for ${group.keys.join(', ')}; keyword-only: ${error instanceof Error ? error.message : String(error)}`);
+            part = await deps.host.search(request);
+        }
+        response.chunks.push(...part.chunks);
+        response.documents.push(...part.documents);
+    }
+    // ── fuse the arms per document ──────────────────────────────────────
+    const fused = new Map();
+    const bump = (catalogKey, documentId, weight, rank, chunk) => {
+        const key = `${catalogKey}\u0000${documentId}`;
+        const entry = fused.get(key) ?? { catalogKey, documentId, score: 0 };
+        entry.score += weight / (RRF_K + rank);
+        // The document's representative chunk: its best vector chunk, else
+        // whichever chunk-FTS row named it.
+        if (chunk && (!entry.chunk || (chunk.cosine ?? -1) > (entry.chunk.cosine ?? -1))) {
+            entry.chunk = chunk;
+        }
+        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
+    // it is (see vector-floors.ts).
+    const textChunks = response.chunks.filter((h) => !h.media);
+    const mediaChunks = response.chunks.filter((h) => h.media);
+    const seenVector = new Set();
+    let vectorRank = 0;
+    for (const hit of textChunks
+        .filter((h) => h.cosine !== undefined)
+        .sort((a, b) => (b.cosine ?? 0) - (a.cosine ?? 0))) {
+        const key = `${hit.catalogKey}\u0000${hit.documentId}`;
+        if (seenVector.has(key))
+            continue;
+        const cosine = hit.cosine ?? 0;
+        const floor = deps.vectorFloorFor(hit.catalogKey);
+        if (floor !== null && cosine < floor)
+            continue;
+        seenVector.add(key);
+        bump(hit.catalogKey, hit.documentId, ARM_WEIGHTS.vector, vectorRank++, hit);
+        const entry = fused.get(key);
+        if (entry && floor !== null && cosine > (entry.similarity ?? Number.NEGATIVE_INFINITY)) {
+            entry.similarity = cosine;
+        }
+    }
+    // Chunk-body FTS arm: BM25 order as the shards returned it, ranked per catalog.
+    const chunkFtsRank = new Map();
+    const seenChunkFts = new Set();
+    for (const hit of textChunks.filter((h) => h.cosine === undefined)) {
+        const key = `${hit.catalogKey}\u0000${hit.documentId}`;
+        if (seenChunkFts.has(key))
+            continue;
+        seenChunkFts.add(key);
+        const rank = chunkFtsRank.get(hit.catalogKey) ?? 0;
+        chunkFtsRank.set(hit.catalogKey, rank + 1);
+        bump(hit.catalogKey, hit.documentId, ARM_WEIGHTS.chunkFts, rank, hit);
+    }
+    // Doc-title FTS arm: exact-name evidence, ranked per catalog by the host.
+    for (const doc of response.documents) {
+        bump(doc.catalogKey, doc.documentId, ARM_WEIGHTS.docFts, doc.rank);
+    }
+    // Media rows: their own vector arm per modality (a modality with no
+    // measured floor gives no vector evidence — nearest-neighbour search
+    // always returns some image, and a media row has no query words to be
+    // grounded in) and a caption FTS arm.
+    const mediaFused = new Map();
+    const bumpMedia = (hit, weight, rank) => {
+        const key = `${hit.catalogKey}\u0000${hit.chunkUid}`;
+        const entry = mediaFused.get(key) ?? {
+            catalogKey: hit.catalogKey,
+            documentId: hit.documentId,
+            score: 0,
+            chunk: hit,
+        };
+        entry.score += weight / (RRF_K + rank);
+        if ((hit.cosine ?? -1) > (entry.chunk?.cosine ?? -1))
+            entry.chunk = hit;
+        mediaFused.set(key, entry);
+    };
+    const mediaVectorRank = new Map();
+    for (const hit of mediaChunks
+        .filter((h) => h.cosine !== undefined)
+        .sort((a, b) => (b.cosine ?? 0) - (a.cosine ?? 0))) {
+        const modality = hit.media?.modality;
+        const floor = deps.vectorFloorFor(hit.catalogKey, modality);
+        if (floor === null || (hit.cosine ?? 0) < floor)
+            continue;
+        const rank = mediaVectorRank.get(modality) ?? 0;
+        mediaVectorRank.set(modality, rank + 1);
+        bumpMedia(hit, MEDIA_ARM_WEIGHTS.vector, rank);
+        const entry = mediaFused.get(`${hit.catalogKey}\u0000${hit.chunkUid}`);
+        if (entry)
+            entry.similarity = Math.max(entry.similarity ?? -1, hit.cosine ?? 0);
+    }
+    let mediaFtsRank = 0;
+    for (const hit of mediaChunks.filter((h) => h.cosine === undefined)) {
+        bumpMedia(hit, MEDIA_ARM_WEIGHTS.chunkFts, mediaFtsRank++);
+    }
+    const ordered = [...fused.values(), ...mediaFused.values()].sort((a, b) => b.score - a.score ||
+        (b.chunk?.cosine ?? -1) - (a.chunk?.cosine ?? -1) ||
+        a.documentId.localeCompare(b.documentId));
+    const matches = new Map([...response.documents, ...response.chunks]
+        .filter((hit) => hit.matchedLocation)
+        .map((hit) => [
+        `${hit.catalogKey}\u0000${hit.documentId}`,
+        { distanceMeters: hit.distanceMeters, matchedLocation: hit.matchedLocation },
+    ]));
+    const seenSpatial = new Set();
+    const out = [];
+    const perCatalogCount = new Map();
+    const capPerCatalog = !opts.spatial && active.length > 1;
+    const mediaPerDocument = new Map();
+    let mediaResults = 0;
+    for (const entry of ordered) {
+        const info = deps.catalog(entry.catalogKey);
+        if (!info)
+            continue;
+        if (entry.chunk?.media) {
+            const docKey = `${entry.catalogKey}\u0000${entry.documentId}`;
+            const forDocument = mediaPerDocument.get(docKey) ?? 0;
+            if (mediaResults >= MEDIA_RESULT_CAP || forDocument >= MEDIA_PER_DOCUMENT)
+                continue;
+            const evidence = entry.similarity !== undefined
+                ? { arm: 'vector', similarity: entry.similarity }
+                : { arm: 'fts' };
+            mediaPerDocument.set(docKey, forDocument + 1);
+            mediaResults++;
+            out.push(knowledgeChunkResult(info, entry.chunk, fusedRankRelevance(out.length), evidence));
+            if (out.length >= Math.max(10, opts.maxResults))
+                break;
+            continue;
+        }
+        const count = perCatalogCount.get(entry.catalogKey) ?? 0;
+        if (capPerCatalog && count >= PER_CATALOG_CAP)
+            continue;
+        const spatialIdentity = spatialDocumentIdentity(info.ref.publisherId, info.ref.catalogId, entry.documentId);
+        if (opts.spatial && seenSpatial.has(spatialIdentity))
+            continue;
+        const relevance = fusedRankRelevance(out.length);
+        // `vector` only when the hit cleared a measured floor; everything else
+        // is lexical evidence, which proactive injection asks to be grounded.
+        const evidence = entry.similarity !== undefined
+            ? { arm: 'vector', similarity: entry.similarity }
+            : { arm: 'fts' };
+        const result = entry.chunk
+            ? knowledgeChunkResult(info, entry.chunk, relevance, evidence)
+            : await knowledgeDocumentResult(deps.host, info, entry.documentId, relevance, evidence);
+        if (!result)
+            continue;
+        perCatalogCount.set(entry.catalogKey, count + 1);
+        seenSpatial.add(spatialIdentity);
+        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 = deps.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(knowledgeChunkResult(info, sibling, fusedRankRelevance(out.length), own));
+            if (out.length >= Math.max(10, opts.maxResults))
+                break;
+        }
+        if (out.length >= Math.max(10, opts.maxResults))
+            break;
+    }
+    return out;
+}
+/** A document the lexical arms named but no chunk carries: cite it with its lead paragraph. */
+export async function knowledgeDocumentResult(host, info, documentId, relevance, evidence) {
+    const doc = await host.getDocument(info.key, documentId).catch(() => null);
+    if (!doc)
+        return null;
+    const snippet = leadExcerpt(doc.markdown) || doc.summary || '';
+    return {
+        kind: 'knowledge',
+        id: `knowledge:${info.ref.catalogId}:doc:${documentId}`,
+        title: doc.title,
+        subtitle: `${info.name} · ${info.topicNames.get(doc.topicId) ?? doc.topicId}`,
+        ...(snippet ? { snippet } : {}),
+        retrievalSource: 'knowledge',
+        catalogId: info.ref.catalogId,
+        catalogVersion: info.ref.version,
+        documentId,
+        topicPath: [info.topicNames.get(doc.topicId) ?? doc.topicId],
+        uri: formatKnowledgeUri({
+            publisherId: info.ref.publisherId,
+            catalogId: info.ref.catalogId,
+            documentId,
+        }),
+        ...(doc.sourceUrl ? { sourceUrl: doc.sourceUrl } : {}),
+        ...evidence,
+        ...scoreResult('knowledge', relevance),
+    };
+}
+export function knowledgeChunkResult(info, hit, relevance, evidence) {
+    return {
+        kind: 'knowledge',
+        id: `knowledge:${info.ref.catalogId}:${hit.chunkUid}`,
+        title: hit.headingPath.length > 0 ? `${hit.title} › ${hit.headingPath.join(' › ')}` : hit.title,
+        subtitle: info.name,
+        snippet: hit.text,
+        retrievalSource: 'knowledge',
+        catalogId: info.ref.catalogId,
+        catalogVersion: info.ref.version,
+        documentId: hit.documentId,
+        uri: formatKnowledgeUri({
+            publisherId: info.ref.publisherId,
+            catalogId: info.ref.catalogId,
+            documentId: hit.documentId,
+            fragment: { chunk: hit.chunkUid },
+        }),
+        line: hit.lineStart,
+        lineEnd: hit.lineEnd,
+        ...(hit.media ? { media: hit.media } : {}),
+        ...evidence,
+        ...scoreResult('knowledge', relevance),
+    };
+}

package/dist/knowledge/worker-host.js

@@ -7,6 +7,7 @@
  */
 import { Worker } from 'node:worker_threads';
 import { createLogger } from '@bendyline/gezel';
+import { disableOnnxRuntimeTelemetry } from '@bendyline/gezel/native';
 import { findServiceWorkerEntry } from '../utils/service-worker-entry.js';
 import { createInProcessCatalogHost } from './catalog-host.js';
 const log = createLogger('knowledge');
@@ -63,6 +64,7 @@ export function createWorkerCatalogHost() {
             return null;
         }
         try {
+            disableOnnxRuntimeTelemetry();
             const w = new Worker(entry);
             w.on('message', (msg) => {
                 const p = pending.get(msg.id);

package/dist/machine-engine/inspect-runtime.js

@@ -1,12 +1,21 @@
+import { innermostErrorReason } from '@bendyline/gezel';
 import { IdentityResponseSchema, certFingerprintFromPem, fingerprintOfPublicKeyPem, verifyIdentitySignature, } from '../remotes/identity.js';
 import { createPinnedFetch } from '../remotes/pinned-fetch.js';
 const MACHINE_REMOTE_ID = 'this-machine';
 export async function inspectMachineRuntime(runtime) {
     const fetchImpl = runtime.cert ? createPinnedFetch(runtime.cert) : fetch;
     try {
-        const response = await fetchImpl(`${runtime.baseUrl}/v1/identity`, {
-            signal: AbortSignal.timeout(5_000),
-        });
+        let response;
+        try {
+            response = await fetchImpl(`${runtime.baseUrl}/v1/identity`, {
+                signal: AbortSignal.timeout(5_000),
+            });
+        }
+        catch (error) {
+            // Bare, this surfaced as `fetch failed` in chat bubbles that never
+            // mentioned a machine engine at all.
+            throw new Error(`Gezel's machine engine at ${runtime.baseUrl} isn't answering (${innermostErrorReason(error)})`, { cause: error });
+        }
         if (!response.ok)
             throw new Error(`identity returned HTTP ${response.status}`);
         const identity = IdentityResponseSchema.parse(await response.json());

package/dist/memory/embed-core.js

@@ -15,6 +15,7 @@
 import { createHash } from 'node:crypto';
 import { createLogger, embeddingProfileArtifacts, } from '@bendyline/gezel';
 import { EmbedderUnavailableError, KNOWLEDGE_EMBEDDING_PROFILES, createProfileEmbedder, resolveTransformersModelOptions, verifyProfileArtifacts, } from '@bendyline/gezel-knowledge';
+import { disableOnnxRuntimeTelemetry } from '@bendyline/gezel/native';
 import { HF_CACHE_DIR_ENV, ModelFileDownloadError, TRANSFORMERS_MODULE, ensureVerifiedModelFile, isCorruptTransformersCacheFailure, isMissingModule, loadTransformersModelWithCacheRecovery, pinTransformersCacheDir, } from '../transformers-cache.js';
 export const log = createLogger('memory');
 /**
@@ -236,6 +237,7 @@ export async function loadPipeline() {
                 // and throws "Unable to get model file path or buffer". The dir is
                 // passed via env so this works in the embed worker thread too, which
                 // inherits `process.env` but has no other view of the gezel home.
+                disableOnnxRuntimeTelemetry();
                 const cacheDir = process.env[HF_CACHE_DIR_ENV];
                 if (cacheDir)
                     await pinTransformersCacheDir(cacheDir);
@@ -348,6 +350,7 @@ async function verifyDaemonPipeline() {
     }
 }
 async function defaultTransformersCacheDir() {
+    disableOnnxRuntimeTelemetry();
     const { env } = await import('@huggingface/transformers');
     // 4.x types it nullable: null only where there is no filesystem cache.
     return env.cacheDir ?? '';

package/dist/memory/embeddings.js

@@ -19,6 +19,7 @@
  */
 import { Worker } from 'node:worker_threads';
 import { createLogger, sameVectorSpace } from '@bendyline/gezel';
+import { disableOnnxRuntimeTelemetry } from '@bendyline/gezel/native';
 import { retireModelWorker } from '../utils/retire-model-worker.js';
 import { findServiceWorkerEntry } from '../utils/service-worker-entry.js';
 import { ModelWorkCancelledError, PipelineLoadError, cancelInFlightModelWork, daemonEmbedderPin, daemonEmbedderVerified, passageInstruction, queryInstruction, runEmbed, runProfileQueryEmbed, } from './embed-core.js';
@@ -124,6 +125,7 @@ function ensureWorker() {
         return null;
     }
     try {
+        disableOnnxRuntimeTelemetry();
         const w = new Worker(entry);
         w.on('message', onMessage);
         w.on('error', (err) => onWorkerDown(err instanceof Error ? err.message : String(err)));

package/dist/models/image-fit.js

@@ -11,12 +11,12 @@
  * 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 { totalMemoryBytes } from '../system/host-memory.js';
 import { detectMemoryProfileCached } from '../system/memory.js';
 import { imageCatalogWeightFiles, sdCppMainComponent } from './weight-facts.js';
 const log = createLogger('media-fit');
@@ -63,7 +63,7 @@ export function imageMediaPool(kind, host = {
 /** 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 ram = totalMemoryBytes();
     const auto = staticCapacityCeilings(budget, ram);
     const configured = configuredEngineMemoryBytes(await readConfig().catch(() => ({})));
     const limited = configured === undefined ? undefined : staticCapacityCeilings(budget, ram, configured);

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

@@ -34,3 +34,8 @@ export declare function localSdCppWeightFiles(model: {
         path: string;
     }>;
 }): Promise<MediaWeightFile[]>;
+/** Weight files on disk, priced from their headers where they are safetensors. */
+export declare function localWeightFiles(entries: ReadonlyArray<{
+    component: string;
+    path: string;
+}>): Promise<MediaWeightFile[]>;

package/dist/models/weight-facts.js

@@ -148,10 +148,13 @@ export function imageCatalogWeightFiles(manifest) {
 }
 /** The weight files of an installed sd-cpp model, headers read from disk. */
 export async function localSdCppWeightFiles(model) {
-    const entries = [
+    return localWeightFiles([
         { component: sdCppMainComponent(model.weightsKind), path: model.weightsPath },
         ...model.auxiliaryFiles.map((a) => ({ component: a.role, path: a.path })),
-    ];
+    ]);
+}
+/** Weight files on disk, priced from their headers where they are safetensors. */
+export async function localWeightFiles(entries) {
     const out = [];
     for (const entry of entries) {
         const format = weightFileFormat(entry.path);

package/dist/providers/ds4/build-provider.js

@@ -123,7 +123,7 @@ export async function buildDs4Provider(opts) {
     // This tier assumes DeepSeek-V4's small resident footprint. A model whose
     // non-routed weights are much larger caps it further via the catalog's
     // `ds4.maxLaunchCtx`; see `resolveDs4LaunchCtx` below.
-    const totalRamBytes = (await import('node:os')).totalmem();
+    const totalRamBytes = (await import('../../system/host-memory.js')).totalMemoryBytes();
     const totalRamGb = totalRamBytes / 1024 ** 3;
     const ramTieredCtx = ds4RamTieredContext(totalRamBytes);
     const ds4ConstrainedToolNoSignalMs = (() => {

package/dist/providers/ds4/residency.js

@@ -1,5 +1,5 @@
-import { totalmem } from 'node:os';
 import { DS4_FULL_RESIDENCY_HEADROOM_BYTES, LLAMA_CPP_VISION_COMPUTE_BYTES, LLAMA_CPP_WEIGHTS_MULTIPLIER, ds4FitsFullResidency, } from '@bendyline/gezel';
+import { totalMemoryBytes } from '../../system/host-memory.js';
 const GB = 1024 ** 3;
 export { DS4_FULL_RESIDENCY_HEADROOM_BYTES };
 /**
@@ -43,7 +43,7 @@ export function ds4BaseResidentBytes(opts) {
 export function canUseDs4FullResidency(opts = {}) {
     return ds4FitsFullResidency({
         modelSizeBytes: opts.modelSizeBytes,
-        totalRamBytes: opts.totalRamBytes ?? totalmem(),
+        totalRamBytes: opts.totalRamBytes ?? totalMemoryBytes(),
         companionBytes: opts.companionBytes,
         platform: opts.platform ?? process.platform,
         arch: opts.arch ?? process.arch,
@@ -82,7 +82,7 @@ export function shouldUseDs4SsdStreaming(opts = {}) {
  * state + the cache cannot consume the runtime/OS reserve.
  */
 export function planDs4ExpertCache(opts) {
-    const totalRamBytes = opts.totalRamBytes ?? totalmem();
+    const totalRamBytes = opts.totalRamBytes ?? totalMemoryBytes();
     const catalogCacheBytes = opts.catalogCacheBytes ?? 0;
     const fixedResidentBytes = Math.max(0, (opts.catalogResidentBytes ?? 0) - catalogCacheBytes);
     const fallbackGb = totalRamBytes >= 120 * GB ? 64 : totalRamBytes >= 88 * GB ? 48 : 32;

package/dist/providers/image/img2img-support.d.ts

@@ -1,5 +1,7 @@
 /**
- * Per-model img2img capability resolution for the local sd-cpp engine.
+ * Per-model image-editing capability for the local sd-cpp engine: whether a
+ * model re-noises a source (img2img), reads sources as references beside an
+ * instruction, or cannot use one. The img2img half first.
  *
  * stable-diffusion.cpp's `/sdapi/v1/img2img` endpoint accepts
  * `init_images` for any loaded model, but whether the *architecture*
@@ -37,4 +39,37 @@ export interface Img2ImgSupportVerdict {
     /** Human-readable reason, set only when unsupported. */
     reason?: string;
 }
+/**
+ * Models that edit by reading source pictures as references beside an
+ * instruction (sd-server's `extra_images`), rather than re-noising one. The
+ * same ladder as above: a catalog `referenceImages` declaration persisted at
+ * pull time wins, then this map, which is how installs that predate the
+ * field learn it.
+ *
+ * FLUX.2 Klein: verified on the pinned engine (native sd-cpp master-975) on
+ * an RTX Spark, 2026-10-27, recoloring, adding an object and composing two
+ * sources at 4 steps in 12 s.
+ */
+export declare const MODEL_REFERENCE_EDIT_SUPPORT: Map<string, {
+    maxImages: number;
+    editOnly?: boolean;
+}>;
+export interface ImageEditCapabilityInput extends Img2ImgSupportInput {
+    /** Explicit `referenceImages` from catalog/installed metadata. */
+    referenceImages?: {
+        max: number;
+    } | undefined;
+    /** Explicit `editOnly` from catalog/installed metadata. */
+    editOnly?: boolean | undefined;
+}
+export interface ImageEditCapability {
+    /** Absent when the model cannot use a source picture at all. */
+    editMode?: 'reference' | 'img2img';
+    /** Sources one edit takes: the reference limit, or 1 for img2img. */
+    maxSourceImages?: number;
+    editOnly: boolean;
+    /** Why the model cannot edit; set only when `editMode` is absent. */
+    reason?: string;
+}
+export declare function resolveImageEditCapability(input: ImageEditCapabilityInput): ImageEditCapability;
 export declare function resolveImg2ImgSupport(input: Img2ImgSupportInput): Img2ImgSupportVerdict;

package/dist/providers/image/img2img-support.js

@@ -1,5 +1,7 @@
 /**
- * Per-model img2img capability resolution for the local sd-cpp engine.
+ * Per-model image-editing capability for the local sd-cpp engine: whether a
+ * model re-noises a source (img2img), reads sources as references beside an
+ * instruction, or cannot use one. The img2img half first.
  *
  * stable-diffusion.cpp's `/sdapi/v1/img2img` endpoint accepts
  * `init_images` for any loaded model, but whether the *architecture*
@@ -44,6 +46,33 @@ export const MODEL_IMG2IMG_SUPPORT = new Map([
     ['krea-2-turbo-q6', false],
     ['krea-2-turbo-q8', false],
 ]);
+/**
+ * Models that edit by reading source pictures as references beside an
+ * instruction (sd-server's `extra_images`), rather than re-noising one. The
+ * same ladder as above: a catalog `referenceImages` declaration persisted at
+ * pull time wins, then this map, which is how installs that predate the
+ * field learn it.
+ *
+ * FLUX.2 Klein: verified on the pinned engine (native sd-cpp master-975) on
+ * an RTX Spark, 2026-10-27, recoloring, adding an object and composing two
+ * sources at 4 steps in 12 s.
+ */
+export const MODEL_REFERENCE_EDIT_SUPPORT = new Map([
+    ['flux-2-klein-4b-q4', { maxImages: 3 }],
+    ['qwen-image-edit-2511-q4', { maxImages: 3, editOnly: true }],
+]);
+export function resolveImageEditCapability(input) {
+    const assessed = input.modelId ? MODEL_REFERENCE_EDIT_SUPPORT.get(input.modelId) : undefined;
+    const editOnly = input.editOnly ?? assessed?.editOnly ?? false;
+    const maxImages = input.referenceImages?.max ?? assessed?.maxImages;
+    if (maxImages !== undefined) {
+        return { editMode: 'reference', maxSourceImages: maxImages, editOnly };
+    }
+    const img2img = resolveImg2ImgSupport(input);
+    if (img2img.supported)
+        return { editMode: 'img2img', maxSourceImages: 1, editOnly };
+    return { editOnly, ...(img2img.reason ? { reason: img2img.reason } : {}) };
+}
 export function resolveImg2ImgSupport(input) {
     if (input.explicit !== undefined) {
         return input.explicit

package/dist/providers/image/local-engine.d.ts

@@ -21,6 +21,7 @@ export interface LocalImageEngineOptions {
 export declare class LocalImageEngine {
     private readonly opts;
     readonly pulls: ImageModelPullRegistry;
+    readonly loraPulls: ImageModelPullRegistry;
     private readonly lifecycle;
     constructor(opts: LocalImageEngineOptions);
     /** Whether this host can render at all: an engine binary, a server URL, or the mock. */