@nhtio/adk/batteries/llm/transformers_js/model_source

Custom model-source resolver for transformers.js — the dual-environment seam that lets a consumer serve a model's files (each submodule ONNX, the tokenizer, the config) from anywhere: OPFS, a different repo per modality, bundled bytes, an in-memory map.

Remarks

Mechanism (verified against the installed @huggingface/transformers build, NODE + WEB, 8 refs each — ungated by IS_NODE_ENV): transformers.js routes every model file through env.customCache.match(key) when env.useCustomCache === true. match may return a Response (bytes), a string (a path/URL the loader then fetches), or undefined (fall through to the normal HF download). This module installs a customCache whose match parses the loader's key back into {repo, filename} and delegates to the user's TransformersJsModelSource hook.

The cache key is the REMOTE URL, not ${repo}/${filename} (corrected at impl from the plan's assumption). buildResourcePaths computes remoteURL = pathJoin(env.remoteHost, env.remotePathTemplate.replace('{model}', repo).replace('{revision}', rev), filename) → https://huggingface.co/<repo>/resolve/<rev>/<path/to/file>. tryCache first probes the local path (no /resolve/ segment — our parser returns undefined, so it correctly falls through) and then this remote URL. parseResourceKey reverses exactly that template.

env is a process-global singleton. withModelSource sets useCustomCache/customCache for the duration of one load and restores the previous values after — behind a module-level async mutex so concurrent loads across adapters never observe each other's hook. installModelSource is the lower-level set-and-return-a-restore-fn primitive for callers that manage their own scope.

The resolver does NOT implement OPFS/bundled reading — it is the plug; the consumer's hook is the implementation. Reused verbatim by the embeddings battery (same env mechanism).

Functions

Function	Description
installModelSource	Install a model-source hook on env and return a restore function. Sets useCustomCache = true + customCache, capturing the previous values. The returned restore() puts them back. NOT mutex- guarded on its own — use withModelSource for the scoped, serialized form.
modelSourceToCache	Wrap a TransformersJsModelSource hook into a Web-Cache-API-compatible object suitable for env.customCache. match parses the key, calls the hook, and normalizes the result: Uint8Array → new Response(bytes); string/Response pass through; undefined/throw → fall through. put is a no-op (served files are never re-cached — toCacheResponse is false for them).
parseResourceKey	Reverse buildResourcePaths' remote-URL key back into {repo, filename}.
withModelSource	Run load() with hook installed on env, then restore — serialized against every other withModelSource call so concurrent adapter loads never clobber the global env. The hook is only active for the duration of load(); after it resolves (or rejects) the prior env cache config is restored even on error.