ngx-transformers 0.3.0 → 0.4.0

package/fesm2022/ngx-transformers.mjs

@@ -1,14 +1,51 @@
 import * as i0 from '@angular/core';
-import { InjectionToken, makeEnvironmentProviders, signal, computed, inject, DestroyRef, input, ChangeDetectionStrategy, Component } from '@angular/core';
+import { InjectionToken, makeEnvironmentProviders, inject, DestroyRef, signal, computed, Injector, resource, untracked, effect, input, ChangeDetectionStrategy, Component } from '@angular/core';
+import { takeOnToken, createWorkerPipelineFactory } from 'ngx-transformers/worker';
 
-const defaultPipelineFactory = async (task, model, options) => {
-    const { pipeline } = await import('@huggingface/transformers');
-    const pipe = await pipeline(task, model, options);
-    return pipe;
-};
+const importTransformers = () => import('@huggingface/transformers');
+/**
+ * Wraps a pipeline so the `onToken` run option (TextGenerator streaming)
+ * becomes a Transformers.js TextStreamer on the pipeline's tokenizer.
+ */
+function withTokenStreaming(pipe, module) {
+    const streaming = (async (input, ...args) => {
+        const { args: rest, onToken } = takeOnToken(args);
+        if (onToken && module.TextStreamer) {
+            const options = { ...rest[rest.length - 1] };
+            options['streamer'] = new module.TextStreamer(pipe.tokenizer, { skip_prompt: true, skip_special_tokens: true, callback_function: onToken });
+            rest[rest.length - 1] = options;
+        }
+        return pipe(input, ...rest);
+    });
+    streaming.dispose = () => pipe.dispose?.() ?? Promise.resolve();
+    return streaming;
+}
+/**
+ * The factory behind PIPELINE_FACTORY. It imports @huggingface/transformers
+ * lazily, on the first pipeline, so the library adds nothing to the initial
+ * bundle. Wrap it to add options or logging while keeping the lazy import:
+ *
+ * ```ts
+ * const base = createDefaultPipelineFactory();
+ * const factory: PipelineFactory = (task, model, options) =>
+ *   base(task, model, { ...options, revision: 'v2' });
+ * providers: [{ provide: PIPELINE_FACTORY, useValue: factory }]
+ * ```
+ *
+ * `load` is the importer. Tests pass a stub module; apps that need to
+ * configure Transformers.js (`env.allowRemoteModels`, `env.localModelPath`)
+ * do it there, before returning the module.
+ */
+function createDefaultPipelineFactory(load = importTransformers) {
+    return async (task, model, options) => {
+        const module = await load();
+        const pipe = (await module.pipeline(task, model, options));
+        return withTokenStreaming(pipe, module);
+    };
+}
 const PIPELINE_FACTORY = new InjectionToken('ngx-transformers.pipeline-factory', {
     providedIn: 'root',
-    factory: () => defaultPipelineFactory,
+    factory: () => createDefaultPipelineFactory(),
 });
 const NGX_TRANSFORMERS_CONFIG = new InjectionToken('ngx-transformers.config', {
     providedIn: 'root',
@@ -26,6 +63,40 @@ const NGX_TRANSFORMERS_CONFIG = new InjectionToken('ngx-transformers.config', {
 function provideTransformers(config) {
     return makeEnvironmentProviders([{ provide: NGX_TRANSFORMERS_CONFIG, useValue: config }]);
 }
+/**
+ * Runs every pipeline in a Web Worker so inference never blocks the UI.
+ * The worker file imports the worker entry point:
+ *
+ * ```ts
+ * // transformers.worker.ts
+ * /// <reference lib="webworker" />
+ * import { runTransformersWorker } from 'ngx-transformers/worker';
+ * runTransformersWorker();
+ *
+ * // app.config.ts
+ * provideTransformersWorker(
+ *   () => new Worker(new URL('./transformers.worker', import.meta.url), { type: 'module' }),
+ * )
+ * ```
+ *
+ * The worker is created on the first pipeline and terminated with the
+ * injector. Handles, signals and the wrappers work unchanged; results must
+ * survive structured cloning (plain objects, arrays, typed arrays and
+ * tensors do). A worker that fails to start rejects the calls waiting on
+ * it, like a failed load in-thread.
+ */
+function provideTransformersWorker(createWorker) {
+    return makeEnvironmentProviders([
+        {
+            provide: PIPELINE_FACTORY,
+            useFactory: () => {
+                const factory = createWorkerPipelineFactory(createWorker);
+                inject(DestroyRef).onDestroy(() => factory.terminate());
+                return factory;
+            },
+        },
+    ]);
+}
 
 let webGpuProbe = null;
 /**
@@ -58,6 +129,7 @@ async function probeWebGpu() {
     }
 }
 
+const newSession = () => ({ pipe: null, loading: null, inFlight: 0, files: new Map() });
 /**
  * A lazily-loaded Transformers.js pipeline wrapped in signals.
  *
@@ -72,18 +144,24 @@ class PipelineHandle {
     /** idle -> loading -> ready <-> busy; error only on load failure. */
     status = signal('idle', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "status" }] : /* istanbul ignore next */ []));
-    /** Download progress for the file currently transferring, else null. */
+    /** Download progress: the file reported last, plus the total over all files. */
     progress = signal(null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "progress" }] : /* istanbul ignore next */ []));
+    /** The last load error; cleared when a load starts. */
     error = signal(null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "error" }] : /* istanbul ignore next */ []));
+    /** The error of the most recently started run, if it failed; cleared when a run starts. */
+    runError = signal(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "runError" }] : /* istanbul ignore next */ []));
     /** True once the model is usable (including while a run is in flight). */
     ready = computed(() => this.status() === 'ready' || this.status() === 'busy', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "ready" }] : /* istanbul ignore next */ []));
     busy = computed(() => this.status() === 'busy' || this.status() === 'loading', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "busy" }] : /* istanbul ignore next */ []));
-    pipe = null;
-    loading = null;
+    session = newSession();
+    destroyed = false;
+    /** Counts runs so only the most recently started one writes runError. */
+    runSequence = 0;
     constructor(request, factory, config) {
         this.request = request;
         this.factory = factory;
@@ -91,12 +169,22 @@ class PipelineHandle {
     }
     /** Downloads and initializes the model. Idempotent; retries after error. */
     load() {
-        if (this.pipe)
+        if (this.destroyed)
+            return Promise.reject(destroyedError());
+        const session = this.session;
+        if (session.pipe)
             return Promise.resolve();
-        this.loading ??= this.doLoad().finally(() => (this.loading = null));
-        return this.loading;
+        session.loading ??= this.doLoad(session).finally(() => {
+            session.loading = null;
+        });
+        return session.loading;
     }
-    /** Runs the pipeline, loading the model first if needed. */
+    /**
+     * Runs the pipeline, loading the model first if needed. Besides the
+     * pipeline's own options, `runOptions.signal` (an AbortSignal) makes the
+     * run reject before it starts when the signal has already fired, which
+     * spares superseded runs the inference (see inferenceResource()).
+     */
     run(input, runOptions) {
         return this.runWith(input, runOptions);
     }
@@ -106,45 +194,96 @@ class PipelineHandle {
      * classification takes (text, candidateLabels, options).
      */
     async runWith(input, ...extraArgs) {
+        const { args, signal } = takeSignal(extraArgs);
         await this.load();
+        // The model cannot be interrupted, but a run nobody wants any more
+        // (a newer input superseded it while the model loaded) need not start.
+        if (signal?.aborted)
+            throw abortError();
+        const session = this.session;
+        const pipe = session.pipe;
+        if (!pipe) {
+            throw new Error('PipelineHandle: disposed before the model finished loading.');
+        }
+        const sequence = ++this.runSequence;
+        session.inFlight++;
         this.status.set('busy');
+        this.runError.set(null);
         try {
-            const pipe = this.pipe;
-            return (await pipe(input, ...extraArgs));
+            return (await pipe(input, ...args));
+        }
+        catch (err) {
+            if (this.session === session && sequence === this.runSequence)
+                this.runError.set(err);
+            throw err;
         }
         finally {
-            // A failed run leaves the model intact - back to ready either way.
-            this.status.set('ready');
+            // Back to ready once the last overlapping run finishes - a failed run
+            // leaves the model intact. A run that outlived dispose() settles its
+            // own, retired session and leaves the status alone.
+            session.inFlight--;
+            if (session.inFlight === 0 && this.session === session)
+                this.status.set('ready');
         }
     }
-    /** Frees the model. The handle can be loaded again afterwards. */
+    /**
+     * Frees the model. A download still in flight is cancelled: its model is
+     * released on arrival and the handle stays idle. The handle can be loaded
+     * again afterwards; destroy() is the terminal variant.
+     */
     async dispose() {
-        const pipe = this.pipe;
-        this.pipe = null;
+        const session = this.session;
+        this.session = newSession();
         this.status.set('idle');
         this.progress.set(null);
-        await pipe?.dispose?.();
+        await session.pipe?.dispose?.();
     }
-    async doLoad() {
+    /**
+     * dispose() for good: later load() and run() calls reject instead of
+     * downloading a model nobody would release. create*() registers this with
+     * the DestroyRef of the injection context, so a handle declared in a
+     * component ends with the component.
+     */
+    destroy() {
+        this.destroyed = true;
+        return this.dispose();
+    }
+    async doLoad(session) {
         this.status.set('loading');
         this.error.set(null);
+        // A retry after a failed attempt starts its bookkeeping from scratch.
+        session.files = new Map();
+        this.progress.set(null);
         const options = {
             ...this.config.pipelineOptions,
             ...this.request.options,
-            progress_callback: (event) => this.onProgress(event),
+            progress_callback: (event) => this.onProgress(event, session),
         };
         const device = await this.resolveDevice();
+        // Disposed while probing the device: do not start the download at all.
+        if (this.session !== session)
+            return;
         const dtype = this.request.dtype ?? this.config.dtype;
         if (device && device !== 'auto')
             options['device'] = device;
         if (dtype)
             options['dtype'] = dtype;
         try {
-            this.pipe = await this.factory(this.request.task, this.request.model, options);
+            const pipe = await this.factory(this.request.task, this.request.model, options);
+            if (this.session !== session) {
+                // Disposed while downloading: nobody wants this model any more.
+                await pipe.dispose?.();
+                return;
+            }
+            session.pipe = pipe;
             this.progress.set(null);
             this.status.set('ready');
         }
         catch (err) {
+            // A cancelled load is not an error - dispose() already reset the handle.
+            if (this.session !== session)
+                return;
+            this.progress.set(null);
             this.error.set(err);
             this.status.set('error');
             throw err;
@@ -160,25 +299,97 @@ class PipelineHandle {
             return configured;
         return this.config.autoDevice ? detectDevice() : configured;
     }
-    onProgress(event) {
-        if (event.status !== 'progress' || !event.file)
+    /**
+     * Transformers.js reports each file on its own (initiate, download,
+     * progress, done). The session records every file it hears about; the
+     * signal is published on progress and done events only, so a file that
+     * has not transferred a byte never replaces the one that is moving.
+     */
+    onProgress(event, session) {
+        // Events from a load that dispose() cancelled must not resurrect the bar.
+        if (this.session !== session || !event.file)
             return;
+        const file = session.files.get(event.file) ?? { loaded: 0, total: 0, done: false };
+        session.files.set(event.file, file);
+        switch (event.status) {
+            case 'progress':
+                file.loaded = event.loaded ?? file.loaded;
+                file.total = event.total ?? file.total;
+                break;
+            case 'done':
+                file.done = true;
+                if (file.total > 0)
+                    file.loaded = file.total;
+                break;
+            default:
+                return; // initiate / download: recorded, not published
+        }
+        const percent = event.status === 'done' ? 100 : Math.round(event.progress ?? 0);
+        const overall = overallOf(session.files);
         this.progress.set({
             file: event.file,
-            progress: Math.round(event.progress ?? 0),
-            loadedBytes: event.loaded ?? 0,
-            totalBytes: event.total ?? 0,
+            progress: percent,
+            loadedBytes: file.loaded,
+            totalBytes: file.total,
+            ...(overall ? { overall } : {}),
         });
     }
 }
+/**
+ * The total over the files seen so far. Transformers.js fetches the small
+ * files (config, tokenizer) before it starts the weights, so a total
+ * computed before the weights are known would read 100% and then collapse;
+ * it is therefore withheld until a weights file has been seen.
+ */
+function overallOf(files) {
+    let weightsSeen = false;
+    let loadedBytes = 0;
+    let totalBytes = 0;
+    let filesDone = 0;
+    for (const [name, file] of files) {
+        if (name.includes('.onnx'))
+            weightsSeen = true;
+        if (file.total > 0) {
+            loadedBytes += Math.min(file.loaded, file.total);
+            totalBytes += file.total;
+        }
+        if (file.done)
+            filesDone++;
+    }
+    if (!weightsSeen)
+        return undefined;
+    return {
+        progress: totalBytes > 0 ? Math.round((loadedBytes / totalBytes) * 100) : 0,
+        loadedBytes,
+        totalBytes,
+        files: files.size,
+        filesDone,
+    };
+}
+/** Pulls `signal` out of a call's trailing options object. */
+function takeSignal(args) {
+    const last = args[args.length - 1];
+    if (typeof last !== 'object' || last === null || Array.isArray(last))
+        return { args };
+    const { signal, ...rest } = last;
+    if (!(signal instanceof AbortSignal))
+        return { args };
+    return { args: [...args.slice(0, -1), rest], signal };
+}
+function abortError() {
+    return new DOMException('PipelineHandle: the run was aborted before it started.', 'AbortError');
+}
+function destroyedError() {
+    return new Error('PipelineHandle: destroyed with its component; create a new handle.');
+}
 /**
  * Creates a PipelineHandle in an injection context (constructor, field
- * initializer, or runInInjectionContext). The handle is disposed with the
+ * initializer, or runInInjectionContext). The handle is destroyed with the
  * surrounding component/injector.
  */
 function createPipeline(request) {
     const handle = new PipelineHandle(request, inject(PIPELINE_FACTORY), inject(NGX_TRANSFORMERS_CONFIG));
-    inject(DestroyRef, { optional: true })?.onDestroy(() => void handle.dispose());
+    inject(DestroyRef, { optional: true })?.onDestroy(() => void handle.destroy());
     return handle;
 }
 
@@ -190,8 +401,8 @@ const DEFAULT_TEXT_CLASSIFICATION_MODEL = 'Xenova/distilbert-base-uncased-finetu
  */
 class TextClassifier extends PipelineHandle {
     /** Classifies one text; resolves to labels sorted by score (top first). */
-    async classify(text, topK = 1) {
-        const out = await this.run(text, { top_k: topK });
+    async classify(text, topK = 1, options = {}) {
+        const out = await this.run(text, { top_k: topK, signal: options.signal });
         // Single input: transformers.js returns a flat array of {label, score}.
         const flat = (Array.isArray(out[0]) ? out[0] : out);
         return [...flat].sort((a, b) => b.score - a.score);
@@ -200,7 +411,7 @@ class TextClassifier extends PipelineHandle {
 /** Creates a TextClassifier in an injection context. */
 function createTextClassifier(options = {}) {
     const classifier = new TextClassifier({ task: 'text-classification', model: DEFAULT_TEXT_CLASSIFICATION_MODEL, ...options }, inject(PIPELINE_FACTORY), inject(NGX_TRANSFORMERS_CONFIG));
-    inject(DestroyRef, { optional: true })?.onDestroy(() => void classifier.dispose());
+    inject(DestroyRef, { optional: true })?.onDestroy(() => void classifier.destroy());
     return classifier;
 }
 
@@ -228,25 +439,29 @@ function cosineSimilarity(a, b) {
  */
 class TextEmbedder extends PipelineHandle {
     /** Embeds one or many texts; always resolves to one vector per text. */
-    async embed(texts) {
+    async embed(texts, options = {}) {
         const input = Array.isArray(texts) ? texts : [texts];
         if (input.length === 0)
             return [];
-        const out = await this.run(input, { pooling: 'mean', normalize: true });
+        const out = await this.run(input, { pooling: 'mean', normalize: true, signal: options.signal });
         return toRows(out);
     }
     /** Cosine similarity of two texts in [-1, 1]. */
-    async similarity(a, b) {
-        const [va, vb] = await this.embed([a, b]);
+    async similarity(a, b, options = {}) {
+        const [va, vb] = await this.embed([a, b], options);
         return cosineSimilarity(va, vb);
     }
     /** Ranks documents against a query, most similar first. */
-    async rank(query, documents) {
+    async rank(query, documents, options = {}) {
         if (documents.length === 0)
             return [];
-        const [queryVec, ...docVecs] = await this.embed([query, ...documents]);
+        const [queryVec, ...docVecs] = await this.embed([query, ...documents], options);
         return docVecs
-            .map((vec, index) => ({ text: documents[index], score: cosineSimilarity(queryVec, vec), index }))
+            .map((vec, index) => ({
+            text: documents[index],
+            score: cosineSimilarity(queryVec, vec),
+            index,
+        }))
             .sort((a, b) => b.score - a.score);
     }
 }
@@ -264,7 +479,7 @@ function toRows(out) {
 /** Creates a TextEmbedder in an injection context. */
 function createTextEmbedder(options = {}) {
     const embedder = new TextEmbedder({ task: 'feature-extraction', model: DEFAULT_EMBEDDING_MODEL, ...options }, inject(PIPELINE_FACTORY), inject(NGX_TRANSFORMERS_CONFIG));
-    inject(DestroyRef, { optional: true })?.onDestroy(() => void embedder.dispose());
+    inject(DestroyRef, { optional: true })?.onDestroy(() => void embedder.destroy());
     return embedder;
 }
 
@@ -324,6 +539,8 @@ class SpeechRecognizer extends PipelineHandle {
             runOptions['language'] = options.language;
         if (options.task !== undefined)
             runOptions['task'] = options.task;
+        if (options.signal !== undefined)
+            runOptions['signal'] = options.signal;
         const raw = await this.run(input, runOptions);
         const first = (Array.isArray(raw) ? raw[0] : raw) ?? {};
         const chunks = first.chunks?.map((c) => ({
@@ -343,7 +560,7 @@ class SpeechRecognizer extends PipelineHandle {
  */
 function createSpeechRecognizer(options = {}) {
     const recognizer = new SpeechRecognizer({ task: 'automatic-speech-recognition', model: DEFAULT_ASR_MODEL, dtype: 'q4', ...options }, inject(PIPELINE_FACTORY), inject(NGX_TRANSFORMERS_CONFIG));
-    inject(DestroyRef, { optional: true })?.onDestroy(() => void recognizer.dispose());
+    inject(DestroyRef, { optional: true })?.onDestroy(() => void recognizer.destroy());
     return recognizer;
 }
 
@@ -370,6 +587,8 @@ class ZeroShotClassifier extends PipelineHandle {
             runOptions['multi_label'] = options.multiLabel;
         if (options.hypothesisTemplate !== undefined)
             runOptions['hypothesis_template'] = options.hypothesisTemplate;
+        if (options.signal !== undefined)
+            runOptions['signal'] = options.signal;
         const raw = await this.runWith(text, [...labels], runOptions);
         const first = Array.isArray(raw) ? raw[0] : raw;
         const scoredLabels = first?.labels ?? [];
@@ -382,7 +601,7 @@ class ZeroShotClassifier extends PipelineHandle {
 /** Creates a ZeroShotClassifier in an injection context. */
 function createZeroShotClassifier(options = {}) {
     const classifier = new ZeroShotClassifier({ task: 'zero-shot-classification', model: DEFAULT_ZERO_SHOT_MODEL, ...options }, inject(PIPELINE_FACTORY), inject(NGX_TRANSFORMERS_CONFIG));
-    inject(DestroyRef, { optional: true })?.onDestroy(() => void classifier.dispose());
+    inject(DestroyRef, { optional: true })?.onDestroy(() => void classifier.destroy());
     return classifier;
 }
 
@@ -418,12 +637,15 @@ class Translator {
     active = signal(null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "active" }] : /* istanbul ignore next */ []));
     handles = new Map();
+    destroyed = false;
     status = computed(() => this.active()?.status() ?? 'idle', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "status" }] : /* istanbul ignore next */ []));
     progress = computed(() => this.active()?.progress() ?? null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "progress" }] : /* istanbul ignore next */ []));
     error = computed(() => this.active()?.error() ?? null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "error" }] : /* istanbul ignore next */ []));
+    runError = computed(() => this.active()?.runError() ?? null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "runError" }] : /* istanbul ignore next */ []));
     ready = computed(() => this.active()?.ready() ?? false, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "ready" }] : /* istanbul ignore next */ []));
     busy = computed(() => this.active()?.busy() ?? false, /* @ts-ignore */
@@ -434,13 +656,13 @@ class Translator {
         this.config = config;
     }
     /** Downloads the model for a pair ahead of the first translate() call. */
-    load(pair = {}) {
+    async load(pair = {}) {
         return this.handleFor(pair).load();
     }
     /** Translates one text; the pair defaults to the one given at creation. */
     async translate(text, pair = {}) {
         const handle = this.handleFor(pair);
-        const raw = await handle.run(text, this.languageOptions(pair));
+        const raw = await handle.run(text, { ...this.languageOptions(pair), signal: pair.signal });
         const first = Array.isArray(raw) ? raw[0] : raw;
         return (first?.translation_text ?? '').trim();
     }
@@ -460,15 +682,32 @@ class Translator {
      * keep several pairs warm and want a progress line per model.
      */
     handleFor(pair = {}) {
+        if (this.destroyed) {
+            throw new Error('Translator: destroyed with its component; create a new translator.');
+        }
         const model = this.modelFor(pair);
         let handle = this.handles.get(model);
         if (!handle) {
-            handle = new PipelineHandle({ task: 'translation', model, device: this.options.device, dtype: this.options.dtype, options: this.options.options }, this.factory, this.config);
+            handle = new PipelineHandle({
+                task: 'translation',
+                model,
+                device: this.options.device,
+                dtype: this.options.dtype,
+                options: this.options.options,
+            }, this.factory, this.config);
             this.handles.set(model, handle);
         }
         this.active.set(handle);
         return handle;
     }
+    /**
+     * dispose() for good: later calls reject instead of loading a model nobody
+     * would release. createTranslator() registers this with the DestroyRef.
+     */
+    destroy() {
+        this.destroyed = true;
+        return this.dispose();
+    }
     /** Frees every model. The translator can be used again afterwards. */
     async dispose() {
         const handles = [...this.handles.values()];
@@ -493,10 +732,124 @@ class Translator {
 /** Creates a Translator in an injection context. */
 function createTranslator(options = {}) {
     const translator = new Translator(options, inject(PIPELINE_FACTORY), inject(NGX_TRANSFORMERS_CONFIG));
-    inject(DestroyRef, { optional: true })?.onDestroy(() => void translator.dispose());
+    inject(DestroyRef, { optional: true })?.onDestroy(() => void translator.destroy());
     return translator;
 }
 
+// The smallest instruct model that holds a conversation; its repository
+// ships the ONNX variants Transformers.js loads (~100 MB at q4).
+const DEFAULT_TEXT_GENERATION_MODEL = 'HuggingFaceTB/SmolLM2-135M-Instruct';
+/**
+ * Text generation with a small language model, streamed token by token.
+ * The default checkpoint is SmolLM2-135M-Instruct; swap `model` for any
+ * Transformers.js text-generation checkpoint (Qwen2.5, Llama, Phi...).
+ */
+class TextGenerator extends PipelineHandle {
+    /** The text generated so far by the latest generate() call; reset when a call starts. */
+    output = signal('', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "output" }] : /* istanbul ignore next */ []));
+    /** Only the most recently started call may write output. */
+    generation = 0;
+    warnedNoStreaming = false;
+    /**
+     * Generates a reply to a prompt or a chat. Tokens stream into `output`
+     * (and `options.onToken`) while the model runs; resolves with the full,
+     * trimmed reply.
+     */
+    async generate(prompt, options = {}) {
+        const runOptions = { max_new_tokens: options.maxNewTokens ?? 256 };
+        if (options.doSample !== undefined)
+            runOptions['do_sample'] = options.doSample;
+        if (options.temperature !== undefined)
+            runOptions['temperature'] = options.temperature;
+        if (options.topP !== undefined)
+            runOptions['top_p'] = options.topP;
+        if (options.topK !== undefined)
+            runOptions['top_k'] = options.topK;
+        if (options.repetitionPenalty !== undefined) {
+            runOptions['repetition_penalty'] = options.repetitionPenalty;
+        }
+        // A plain prompt would otherwise come back with the prompt in front.
+        if (typeof prompt === 'string')
+            runOptions['return_full_text'] = false;
+        if (options.signal !== undefined)
+            runOptions['signal'] = options.signal;
+        const generation = ++this.generation;
+        let streamed = 0;
+        this.output.set('');
+        runOptions['onToken'] = (text) => {
+            streamed++;
+            if (generation === this.generation)
+                this.output.update((current) => current + text);
+            options.onToken?.(text);
+        };
+        const raw = await this.run(prompt, runOptions);
+        const first = Array.isArray(raw) ? raw[0] : raw;
+        const generated = first?.generated_text;
+        const text = Array.isArray(generated) ? (generated.at(-1)?.content ?? '') : (generated ?? '');
+        const reply = text.trim();
+        if (generation === this.generation)
+            this.output.set(reply);
+        if (streamed === 0 && reply && !this.warnedNoStreaming) {
+            // Streaming relies on the pipeline factory turning the onToken run
+            // option into a TextStreamer, which the built-in factories do. A
+            // custom factory that returns a raw pipeline drops it silently.
+            this.warnedNoStreaming = true;
+            console.warn('ngx-transformers: the reply arrived without streamed tokens. A custom PIPELINE_FACTORY must wrap createDefaultPipelineFactory() (or handle the onToken run option) for TextGenerator.output to stream.');
+        }
+        return reply;
+    }
+}
+/**
+ * Creates a TextGenerator in an injection context; destroyed with the
+ * component. dtype defaults to 'q4', the size/quality sweet spot for small
+ * decoders on the WebAssembly runtime.
+ */
+function createTextGenerator(options = {}) {
+    const generator = new TextGenerator({ task: 'text-generation', model: DEFAULT_TEXT_GENERATION_MODEL, dtype: 'q4', ...options }, inject(PIPELINE_FACTORY), inject(NGX_TRANSFORMERS_CONFIG));
+    inject(DestroyRef, { optional: true })?.onDestroy(() => void generator.destroy());
+    return generator;
+}
+
+/**
+ * Runs inference whenever an input signal changes, as an Angular resource:
+ * `value()`, `isLoading()`, `error()` and `status()` are signals, and only
+ * the result for the latest input is kept.
+ *
+ * ```ts
+ * readonly text = signal('');
+ * readonly classifier = createTextClassifier();
+ * readonly sentiment = inferenceResource({
+ *   input: () => this.text().trim() || undefined,
+ *   run: (text, signal) => this.classifier.classify(text, 1, { signal }),
+ *   debounceMs: 300,
+ * });
+ * // template: @if (sentiment.value(); as result) { {{ result[0].label }} }
+ * ```
+ */
+function inferenceResource(options) {
+    const injector = options.injector ?? inject(Injector);
+    const input = options.debounceMs
+        ? debounced(options.input, options.debounceMs, injector)
+        : options.input;
+    return resource({
+        params: () => input(),
+        loader: ({ params, abortSignal }) => options.run(params, abortSignal),
+        injector,
+    });
+}
+/** A signal that follows `source` once it has been stable for `ms`. */
+function debounced(source, ms, injector) {
+    const out = signal(untracked(source), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "out" }] : /* istanbul ignore next */ []));
+    effect((onCleanup) => {
+        const value = source();
+        const timer = setTimeout(() => out.set(value), ms);
+        onCleanup(() => clearTimeout(timer));
+    }, { injector });
+    return out.asReadonly();
+}
+
 /**
  * Microphone capture with a signals API. start() asks for mic permission
  * and records; stop() resolves with the encoded audio Blob - pass it to
@@ -598,7 +951,8 @@ function createMicRecorder(deps = {}) {
 
 /**
  * Drop-in status line for a PipelineHandle: shows model download progress
- * while loading, then the ready/busy/error state. Themeable via CSS custom
+ * (over every file of the model) while loading, then the ready/busy/error
+ * state. Themeable via CSS custom
  * properties (--nt-accent, --nt-ink, --nt-muted, --nt-track).
  *
  * ```html
@@ -613,6 +967,10 @@ class ModelProgressComponent {
     /** Labels per status; override to localize. */
     labels = input({}, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "labels" }] : /* istanbul ignore next */ []));
+    /** The bar follows the whole download when the handle reports it, else the current file. */
+    percent(progress) {
+        return progress.overall?.progress ?? progress.progress;
+    }
     label = computed(() => {
         const defaults = {
             idle: 'Model not loaded',
@@ -624,22 +982,31 @@ class ModelProgressComponent {
         return this.labels()[this.status()] ?? defaults[this.status()];
     }, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "label" }] : /* istanbul ignore next */ []));
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.5", ngImport: i0, type: ModelProgressComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.1.5", type: ModelProgressComponent, isStandalone: true, selector: "ngx-model-progress", inputs: { status: { classPropertyName: "status", publicName: "status", isSignal: true, isRequired: true, transformFunction: null }, progress: { classPropertyName: "progress", publicName: "progress", isSignal: true, isRequired: false, transformFunction: null }, labels: { classPropertyName: "labels", publicName: "labels", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0, template: `
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.6", ngImport: i0, type: ModelProgressComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.1.6", type: ModelProgressComponent, isStandalone: true, selector: "ngx-model-progress", inputs: { status: { classPropertyName: "status", publicName: "status", isSignal: true, isRequired: true, transformFunction: null }, progress: { classPropertyName: "progress", publicName: "progress", isSignal: true, isRequired: false, transformFunction: null }, labels: { classPropertyName: "labels", publicName: "labels", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0, template: `
     <div class="nt-row" [class.nt-error]="status() === 'error'" role="status">
       <span class="nt-dot" [attr.data-status]="status()"></span>
       <span class="nt-label">{{ label() }}</span>
       @if (status() === 'loading' && progress(); as p) {
         <span class="nt-file">{{ p.file }}</span>
-        <div class="nt-track" role="progressbar" [attr.aria-valuenow]="p.progress" aria-valuemin="0" aria-valuemax="100">
-          <div class="nt-fill" [style.width.%]="p.progress"></div>
+        @if (p.overall && p.overall.files > 1) {
+          <span class="nt-files">{{ p.overall.filesDone }}/{{ p.overall.files }} files</span>
+        }
+        <div
+          class="nt-track"
+          role="progressbar"
+          [attr.aria-valuenow]="percent(p)"
+          aria-valuemin="0"
+          aria-valuemax="100"
+        >
+          <div class="nt-fill" [style.width.%]="percent(p)"></div>
         </div>
-        <span class="nt-pct">{{ p.progress }}%</span>
+        <span class="nt-pct">{{ percent(p) }}%</span>
       }
     </div>
-  `, isInline: true, styles: [":host{--nt-accent: #f59e0b;--nt-ink: #1e293b;--nt-muted: #64748b;--nt-track: #e2e8f0;display:block;font-size:12.5px;color:var(--nt-ink)}.nt-row{display:flex;align-items:center;gap:8px}.nt-dot{width:8px;height:8px;border-radius:50%;flex:none;background:var(--nt-muted)}.nt-dot[data-status=loading]{background:var(--nt-accent);animation:nt-blink 1s ease-in-out infinite}.nt-dot[data-status=ready]{background:#22c55e}.nt-dot[data-status=busy]{background:#3b82f6;animation:nt-blink .7s ease-in-out infinite}.nt-dot[data-status=error]{background:#dc2626}.nt-label{font-weight:600}.nt-file{color:var(--nt-muted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap;max-width:180px}.nt-track{flex:1;min-width:60px;height:6px;border-radius:3px;background:var(--nt-track);overflow:hidden}.nt-fill{height:100%;background:var(--nt-accent);border-radius:3px;transition:width .12s linear}.nt-pct{font-variant-numeric:tabular-nums;color:var(--nt-muted)}.nt-error .nt-label{color:#dc2626}@keyframes nt-blink{0%,to{opacity:1}50%{opacity:.35}}@media(prefers-reduced-motion:reduce){.nt-dot{animation:none}.nt-fill{transition:none}}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+  `, isInline: true, styles: [":host{--nt-accent: #f59e0b;--nt-ink: #1e293b;--nt-muted: #64748b;--nt-track: #e2e8f0;display:block;font-size:12.5px;color:var(--nt-ink)}.nt-row{display:flex;align-items:center;gap:8px}.nt-dot{width:8px;height:8px;border-radius:50%;flex:none;background:var(--nt-muted)}.nt-dot[data-status=loading]{background:var(--nt-accent);animation:nt-blink 1s ease-in-out infinite}.nt-dot[data-status=ready]{background:#22c55e}.nt-dot[data-status=busy]{background:#3b82f6;animation:nt-blink .7s ease-in-out infinite}.nt-dot[data-status=error]{background:#dc2626}.nt-label{font-weight:600}.nt-file{color:var(--nt-muted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap;max-width:180px}.nt-track{flex:1;min-width:60px;height:6px;border-radius:3px;background:var(--nt-track);overflow:hidden}.nt-fill{height:100%;background:var(--nt-accent);border-radius:3px;transition:width .12s linear}.nt-files{color:var(--nt-muted);white-space:nowrap}.nt-pct{font-variant-numeric:tabular-nums;color:var(--nt-muted)}.nt-error .nt-label{color:#dc2626}@keyframes nt-blink{0%,to{opacity:1}50%{opacity:.35}}@media(prefers-reduced-motion:reduce){.nt-dot{animation:none}.nt-fill{transition:none}}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.5", ngImport: i0, type: ModelProgressComponent, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.6", ngImport: i0, type: ModelProgressComponent, decorators: [{
             type: Component,
             args: [{ selector: 'ngx-model-progress', changeDetection: ChangeDetectionStrategy.OnPush, template: `
     <div class="nt-row" [class.nt-error]="status() === 'error'" role="status">
@@ -647,22 +1014,34 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.5", ngImpor
       <span class="nt-label">{{ label() }}</span>
       @if (status() === 'loading' && progress(); as p) {
         <span class="nt-file">{{ p.file }}</span>
-        <div class="nt-track" role="progressbar" [attr.aria-valuenow]="p.progress" aria-valuemin="0" aria-valuemax="100">
-          <div class="nt-fill" [style.width.%]="p.progress"></div>
+        @if (p.overall && p.overall.files > 1) {
+          <span class="nt-files">{{ p.overall.filesDone }}/{{ p.overall.files }} files</span>
+        }
+        <div
+          class="nt-track"
+          role="progressbar"
+          [attr.aria-valuenow]="percent(p)"
+          aria-valuemin="0"
+          aria-valuemax="100"
+        >
+          <div class="nt-fill" [style.width.%]="percent(p)"></div>
         </div>
-        <span class="nt-pct">{{ p.progress }}%</span>
+        <span class="nt-pct">{{ percent(p) }}%</span>
       }
     </div>
-  `, styles: [":host{--nt-accent: #f59e0b;--nt-ink: #1e293b;--nt-muted: #64748b;--nt-track: #e2e8f0;display:block;font-size:12.5px;color:var(--nt-ink)}.nt-row{display:flex;align-items:center;gap:8px}.nt-dot{width:8px;height:8px;border-radius:50%;flex:none;background:var(--nt-muted)}.nt-dot[data-status=loading]{background:var(--nt-accent);animation:nt-blink 1s ease-in-out infinite}.nt-dot[data-status=ready]{background:#22c55e}.nt-dot[data-status=busy]{background:#3b82f6;animation:nt-blink .7s ease-in-out infinite}.nt-dot[data-status=error]{background:#dc2626}.nt-label{font-weight:600}.nt-file{color:var(--nt-muted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap;max-width:180px}.nt-track{flex:1;min-width:60px;height:6px;border-radius:3px;background:var(--nt-track);overflow:hidden}.nt-fill{height:100%;background:var(--nt-accent);border-radius:3px;transition:width .12s linear}.nt-pct{font-variant-numeric:tabular-nums;color:var(--nt-muted)}.nt-error .nt-label{color:#dc2626}@keyframes nt-blink{0%,to{opacity:1}50%{opacity:.35}}@media(prefers-reduced-motion:reduce){.nt-dot{animation:none}.nt-fill{transition:none}}\n"] }]
+  `, styles: [":host{--nt-accent: #f59e0b;--nt-ink: #1e293b;--nt-muted: #64748b;--nt-track: #e2e8f0;display:block;font-size:12.5px;color:var(--nt-ink)}.nt-row{display:flex;align-items:center;gap:8px}.nt-dot{width:8px;height:8px;border-radius:50%;flex:none;background:var(--nt-muted)}.nt-dot[data-status=loading]{background:var(--nt-accent);animation:nt-blink 1s ease-in-out infinite}.nt-dot[data-status=ready]{background:#22c55e}.nt-dot[data-status=busy]{background:#3b82f6;animation:nt-blink .7s ease-in-out infinite}.nt-dot[data-status=error]{background:#dc2626}.nt-label{font-weight:600}.nt-file{color:var(--nt-muted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap;max-width:180px}.nt-track{flex:1;min-width:60px;height:6px;border-radius:3px;background:var(--nt-track);overflow:hidden}.nt-fill{height:100%;background:var(--nt-accent);border-radius:3px;transition:width .12s linear}.nt-files{color:var(--nt-muted);white-space:nowrap}.nt-pct{font-variant-numeric:tabular-nums;color:var(--nt-muted)}.nt-error .nt-label{color:#dc2626}@keyframes nt-blink{0%,to{opacity:1}50%{opacity:.35}}@media(prefers-reduced-motion:reduce){.nt-dot{animation:none}.nt-fill{transition:none}}\n"] }]
         }], propDecorators: { status: [{ type: i0.Input, args: [{ isSignal: true, alias: "status", required: true }] }], progress: [{ type: i0.Input, args: [{ isSignal: true, alias: "progress", required: false }] }], labels: [{ type: i0.Input, args: [{ isSignal: true, alias: "labels", required: false }] }] } });
 
-/*
- * Public API Surface of ngx-transformers
+/**
+ * Public API surface of ngx-transformers: handles, wrappers, configuration
+ * and the progress component.
+ *
+ * @module ngx-transformers
  */
 
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { DEFAULT_ASR_MODEL, DEFAULT_EMBEDDING_MODEL, DEFAULT_TEXT_CLASSIFICATION_MODEL, DEFAULT_ZERO_SHOT_MODEL, MicRecorder, ModelProgressComponent, NGX_TRANSFORMERS_CONFIG, PIPELINE_FACTORY, PipelineHandle, SpeechRecognizer, TextClassifier, TextEmbedder, Translator, WHISPER_SAMPLE_RATE, ZeroShotClassifier, cosineSimilarity, createMicRecorder, createPipeline, createSpeechRecognizer, createTextClassifier, createTextEmbedder, createTranslator, createZeroShotClassifier, decodeAudio, defaultTranslationModel, detectDevice, hasWebGpu, provideTransformers, resetDeviceDetection, resolveTranslationModel };
+export { DEFAULT_ASR_MODEL, DEFAULT_EMBEDDING_MODEL, DEFAULT_TEXT_CLASSIFICATION_MODEL, DEFAULT_TEXT_GENERATION_MODEL, DEFAULT_ZERO_SHOT_MODEL, MicRecorder, ModelProgressComponent, NGX_TRANSFORMERS_CONFIG, PIPELINE_FACTORY, PipelineHandle, SpeechRecognizer, TextClassifier, TextEmbedder, TextGenerator, Translator, WHISPER_SAMPLE_RATE, ZeroShotClassifier, cosineSimilarity, createDefaultPipelineFactory, createMicRecorder, createPipeline, createSpeechRecognizer, createTextClassifier, createTextEmbedder, createTextGenerator, createTranslator, createZeroShotClassifier, decodeAudio, defaultTranslationModel, detectDevice, hasWebGpu, inferenceResource, provideTransformers, provideTransformersWorker, resetDeviceDetection, resolveTranslationModel };
 //# sourceMappingURL=ngx-transformers.mjs.map