/**
 * 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.
 *
 * @module @nhtio/adk/batteries/llm/transformers_js/model_source
 *
 * @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 {@link 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. {@link parseResourceKey} reverses exactly that template.
 *
 * **`env` is a process-global singleton.** {@link 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. {@link 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).
 */
import type { TransformersJsModelSource } from "./types";
/** The cache shape transformers.js requires (`match` + `put`, Web Cache API subset). */
interface TransformersCacheLike {
    match: (request: string) => Promise<Response | string | undefined>;
    put: (request: string, response: Response) => Promise<void>;
}
/** The mutable `env` surface we touch — kept minimal + structurally typed (no peer import here). */
interface TransformersEnvLike {
    useCustomCache: boolean;
    customCache: TransformersCacheLike | null;
    remoteHost?: string;
    remotePathTemplate?: string;
}
/**
 * Reverse `buildResourcePaths`' remote-URL key back into `{repo, filename}`.
 *
 * Handles the canonical `{host}{model}/resolve/{revision}/{filename}` template. Returns `undefined`
 * for any key that is not a remote-host URL (e.g. the local-path probe `tryCache` issues first), so the
 * caller falls through to the default loader instead of mis-routing.
 *
 * @param key - The string transformers.js passes to `cache.match` (the remote URL).
 * @param env - The (possibly customized) host/template; defaults match the library's own defaults.
 */
export declare const parseResourceKey: (key: string, env?: {
    remoteHost?: string;
    remotePathTemplate?: string;
}) => {
    repo: string;
    filename: string;
} | undefined;
/**
 * Wrap a {@link 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).
 *
 * @param hook - The consumer's resolver.
 * @param env - Host/template for key parsing (defaults to the library defaults).
 */
export declare const modelSourceToCache: (hook: TransformersJsModelSource, env?: {
    remoteHost?: string;
    remotePathTemplate?: string;
}) => TransformersCacheLike;
/**
 * 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 {@link withModelSource} for the scoped, serialized form.
 *
 * @param env - The transformers.js `env` object (from `await import('@huggingface/transformers')`).
 * @param hook - The resolver to install.
 * @returns A function that restores `env`'s prior cache configuration.
 */
export declare const installModelSource: (env: TransformersEnvLike, hook: TransformersJsModelSource) => (() => void);
/**
 * 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.
 *
 * @param env - The transformers.js `env` object.
 * @param hook - The resolver to install for this load.
 * @param load - The async load operation (e.g. `pipeline(...)` / `from_pretrained(...)`).
 */
export declare const withModelSource: <T>(env: TransformersEnvLike, hook: TransformersJsModelSource, load: () => Promise<T>) => Promise<T>;
export {};