ngx-transformers 0.3.0 → 0.4.0

package/types/ngx-transformers.d.ts

@@ -1,5 +1,6 @@
 import * as _angular_core from '@angular/core';
-import { InjectionToken, EnvironmentProviders } from '@angular/core';
+import { InjectionToken, EnvironmentProviders, Injector, ResourceRef } from '@angular/core';
+import { WorkerLike } from 'ngx-transformers/worker';
 import * as ngx_transformers from 'ngx-transformers';
 
 /** Lifecycle of a model pipeline. `error` is terminal until load() is retried. */
@@ -12,9 +13,27 @@ interface ModelProgress {
     progress: number;
     loadedBytes: number;
     totalBytes: number;
+    /** Progress over every file of the model seen so far; absent when unknown. */
+    overall?: OverallProgress;
+}
+/**
+ * Download progress summed over the files of a model seen so far. A model
+ * is several files (config, tokenizer, weights) fetched in parallel; this is
+ * the steady number to put on a progress bar.
+ */
+interface OverallProgress {
+    /** 0-100 over the bytes of every file with a known size. */
+    progress: number;
+    loadedBytes: number;
+    totalBytes: number;
+    /** Files seen so far. */
+    files: number;
+    /** Files fully downloaded. */
+    filesDone: number;
 }
 type TransformersDevice = 'wasm' | 'webgpu' | 'auto';
-type TransformersDtype = 'fp32' | 'fp16' | 'q8' | 'q4';
+/** Weight formats Transformers.js can load; a checkpoint must ship the one you ask for. */
+type TransformersDtype = 'fp32' | 'fp16' | 'q8' | 'int8' | 'uint8' | 'q4' | 'bnb4' | 'q4f16';
 /** Global defaults applied to every pipeline; see provideTransformers(). */
 interface NgxTransformersConfig {
     device?: TransformersDevice;
@@ -41,6 +60,14 @@ interface PipelineRequest {
     dtype?: TransformersDtype;
     options?: Record<string, unknown>;
 }
+/**
+ * Options every run accepts. `signal` makes a run reject with an AbortError
+ * before it starts when the signal has already fired; a model run cannot be
+ * interrupted once started, but a superseded run need not begin.
+ */
+interface RunOptions {
+    signal?: AbortSignal;
+}
 interface ClassificationResult {
     label: string;
     score: number;
@@ -65,7 +92,7 @@ interface Transcription {
     /** Present when transcribe() was called with returnTimestamps. */
     chunks?: TranscriptionChunk[];
 }
-interface TranscribeOptions {
+interface TranscribeOptions extends RunOptions {
     /** true for segment timestamps, 'word' for word-level. */
     returnTimestamps?: boolean | 'word';
     /** Split audio longer than ~30 s into chunks of this many seconds. */
@@ -78,7 +105,7 @@ interface TranscribeOptions {
     task?: 'transcribe' | 'translate';
 }
 /** Options for ZeroShotClassifier.classify(). */
-interface ZeroShotOptions {
+interface ZeroShotOptions extends RunOptions {
     /** Score every label on its own (several can be high) instead of picking one. */
     multiLabel?: boolean;
     /** NLI hypothesis with a {} placeholder for the label; default "This example is {}.". */
@@ -88,7 +115,7 @@ interface ZeroShotOptions {
  * Language pair for one translate() call. Codes follow the checkpoint:
  * ISO 639-1 for opus-mt ("en", "ru"), FLORES-200 for NLLB ("eng_Latn").
  */
-interface TranslateOptions {
+interface TranslateOptions extends RunOptions {
     from?: string;
     to?: string;
 }
@@ -99,6 +126,24 @@ interface TranslatorOptions extends Partial<Omit<PipelineRequest, 'task'>> {
     /** Default target language for translate(). */
     to?: string;
 }
+/** One turn of a chat prompt for TextGenerator. */
+interface ChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+/** Options for TextGenerator.generate(). */
+interface GenerateOptions extends RunOptions {
+    /** Upper bound on generated tokens; default 256. */
+    maxNewTokens?: number;
+    /** Sample instead of greedy decoding; set with temperature / topP / topK. */
+    doSample?: boolean;
+    temperature?: number;
+    topP?: number;
+    topK?: number;
+    repetitionPenalty?: number;
+    /** Called with each piece of text as it is generated. */
+    onToken?: (text: string) => void;
+}
 
 /**
  * The callable returned by Transformers.js pipeline(), reduced to the
@@ -112,6 +157,37 @@ type PipelineLike = ((input: unknown, options?: Record<string, unknown>) => Prom
  * @huggingface/transformers; tests and SSR shims can provide their own.
  */
 type PipelineFactory = (task: string, model: string | undefined, options: Record<string, unknown>) => Promise<PipelineLike>;
+/**
+ * The slice of the @huggingface/transformers module the default factory
+ * uses. The real module satisfies it, so an importer can configure
+ * `env` and return the module as is.
+ */
+interface TransformersModuleLike {
+    pipeline(task: string, model?: string, options?: object): Promise<unknown>;
+    /** Streams generated text for the `onToken` run option; optional in test stubs. */
+    TextStreamer?: new (tokenizer: never, options: {
+        skip_prompt?: boolean;
+        skip_special_tokens?: boolean;
+        callback_function?: (text: string) => void;
+    }) => unknown;
+}
+/**
+ * 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.
+ */
+declare function createDefaultPipelineFactory(load?: () => Promise<TransformersModuleLike>): PipelineFactory;
 declare const PIPELINE_FACTORY: InjectionToken<PipelineFactory>;
 declare const NGX_TRANSFORMERS_CONFIG: InjectionToken<NgxTransformersConfig>;
 /**
@@ -124,6 +200,29 @@ declare const NGX_TRANSFORMERS_CONFIG: InjectionToken<NgxTransformersConfig>;
  * ```
  */
 declare function provideTransformers(config: NgxTransformersConfig): EnvironmentProviders;
+/**
+ * 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.
+ */
+declare function provideTransformersWorker(createWorker: () => WorkerLike): EnvironmentProviders;
 
 /**
  * A lazily-loaded Transformers.js pipeline wrapped in signals.
@@ -138,18 +237,28 @@ declare class PipelineHandle<TIn = unknown, TOut = unknown> {
     private readonly config;
     /** idle -> loading -> ready <-> busy; error only on load failure. */
     readonly status: _angular_core.WritableSignal<PipelineStatus>;
-    /** Download progress for the file currently transferring, else null. */
+    /** Download progress: the file reported last, plus the total over all files. */
     readonly progress: _angular_core.WritableSignal<ModelProgress | null>;
+    /** The last load error; cleared when a load starts. */
     readonly error: _angular_core.WritableSignal<unknown>;
+    /** The error of the most recently started run, if it failed; cleared when a run starts. */
+    readonly runError: _angular_core.WritableSignal<unknown>;
     /** True once the model is usable (including while a run is in flight). */
     readonly ready: _angular_core.Signal<boolean>;
     readonly busy: _angular_core.Signal<boolean>;
-    private pipe;
-    private loading;
+    private session;
+    private destroyed;
+    /** Counts runs so only the most recently started one writes runError. */
+    private runSequence;
     constructor(request: PipelineRequest, factory: PipelineFactory, config: NgxTransformersConfig);
     /** Downloads and initializes the model. Idempotent; retries after error. */
     load(): Promise<void>;
-    /** 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: TIn, runOptions?: Record<string, unknown>): Promise<TOut>;
     /**
      * Runs the pipeline with extra positional arguments after the input, for
@@ -157,19 +266,36 @@ declare class PipelineHandle<TIn = unknown, TOut = unknown> {
      * classification takes (text, candidateLabels, options).
      */
     protected runWith(input: TIn, ...extraArgs: unknown[]): Promise<TOut>;
-    /** 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.
+     */
     dispose(): Promise<void>;
+    /**
+     * 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(): Promise<void>;
     private doLoad;
     /**
      * An explicit request or global device wins; with `autoDevice` on, an
      * unset or 'auto' device is probed for WebGPU (once, cached) at load time.
      */
     private resolveDevice;
+    /**
+     * 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.
+     */
     private onProgress;
 }
 /**
  * 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.
  */
 declare function createPipeline<TIn = unknown, TOut = unknown>(request: PipelineRequest): PipelineHandle<TIn, TOut>;
@@ -194,7 +320,7 @@ declare const DEFAULT_TEXT_CLASSIFICATION_MODEL = "Xenova/distilbert-base-uncase
  */
 declare class TextClassifier extends PipelineHandle<string, ClassificationResult[] | ClassificationResult[][]> {
     /** Classifies one text; resolves to labels sorted by score (top first). */
-    classify(text: string, topK?: number): Promise<ClassificationResult[]>;
+    classify(text: string, topK?: number, options?: RunOptions): Promise<ClassificationResult[]>;
 }
 /** Creates a TextClassifier in an injection context. */
 declare function createTextClassifier(options?: Partial<Omit<PipelineRequest, 'task'>>): TextClassifier;
@@ -215,11 +341,11 @@ declare function cosineSimilarity(a: readonly number[], b: readonly number[]): n
  */
 declare class TextEmbedder extends PipelineHandle<string | string[], TensorLike> {
     /** Embeds one or many texts; always resolves to one vector per text. */
-    embed(texts: string | string[]): Promise<number[][]>;
+    embed(texts: string | string[], options?: RunOptions): Promise<number[][]>;
     /** Cosine similarity of two texts in [-1, 1]. */
-    similarity(a: string, b: string): Promise<number>;
+    similarity(a: string, b: string, options?: RunOptions): Promise<number>;
     /** Ranks documents against a query, most similar first. */
-    rank(query: string, documents: string[]): Promise<RankedResult[]>;
+    rank(query: string, documents: string[], options?: RunOptions): Promise<RankedResult[]>;
 }
 /** Creates a TextEmbedder in an injection context. */
 declare function createTextEmbedder(options?: Partial<Omit<PipelineRequest, 'task'>>): TextEmbedder;
@@ -313,9 +439,11 @@ declare class Translator {
     private readonly config;
     private readonly active;
     private readonly handles;
+    private destroyed;
     readonly status: _angular_core.Signal<ngx_transformers.PipelineStatus>;
     readonly progress: _angular_core.Signal<ngx_transformers.ModelProgress | null>;
     readonly error: _angular_core.Signal<{} | null>;
+    readonly runError: _angular_core.Signal<{} | null>;
     readonly ready: _angular_core.Signal<boolean>;
     readonly busy: _angular_core.Signal<boolean>;
     constructor(options: TranslatorOptions, factory: PipelineFactory, config: NgxTransformersConfig);
@@ -330,6 +458,11 @@ declare class Translator {
      * keep several pairs warm and want a progress line per model.
      */
     handleFor(pair?: TranslateOptions): TranslationHandle;
+    /**
+     * dispose() for good: later calls reject instead of loading a model nobody
+     * would release. createTranslator() registers this with the DestroyRef.
+     */
+    destroy(): Promise<void>;
     /** Frees every model. The translator can be used again afterwards. */
     dispose(): Promise<void>;
     /** src_lang / tgt_lang for multilingual checkpoints; opus-mt models get nothing. */
@@ -338,6 +471,72 @@ declare class Translator {
 /** Creates a Translator in an injection context. */
 declare function createTranslator(options?: TranslatorOptions): Translator;
 
+declare const DEFAULT_TEXT_GENERATION_MODEL = "HuggingFaceTB/SmolLM2-135M-Instruct";
+/** Raw text-generation output: the reply as a string, or the chat with the reply appended. */
+interface RawGeneration {
+    generated_text?: string | ChatMessage[];
+}
+/**
+ * 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...).
+ */
+declare class TextGenerator extends PipelineHandle<string | ChatMessage[], RawGeneration | RawGeneration[]> {
+    /** The text generated so far by the latest generate() call; reset when a call starts. */
+    readonly output: _angular_core.WritableSignal<string>;
+    /** Only the most recently started call may write output. */
+    private generation;
+    private warnedNoStreaming;
+    /**
+     * 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.
+     */
+    generate(prompt: string | ChatMessage[], options?: GenerateOptions): Promise<string>;
+}
+/**
+ * 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.
+ */
+declare function createTextGenerator(options?: Partial<Omit<PipelineRequest, 'task'>>): TextGenerator;
+
+interface InferenceResourceOptions<TIn, TOut> {
+    /**
+     * The input to run on, read reactively. Return `undefined` for "nothing
+     * to do": the resource stays idle and keeps no value.
+     */
+    input: () => TIn | undefined;
+    /**
+     * Runs the model for one input, typically a handle method. The abort
+     * signal fires when a newer input supersedes this run: pass it on as the
+     * method's `signal` option and a superseded run that has not started yet
+     * (it was waiting for the model to load) is skipped instead of queued.
+     */
+    run: (input: TIn, abortSignal: AbortSignal) => Promise<TOut>;
+    /** Wait this long after the last input change before running (typing). */
+    debounceMs?: number;
+    /** Required outside an injection context. */
+    injector?: Injector;
+}
+/**
+ * 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 }} }
+ * ```
+ */
+declare function inferenceResource<TIn, TOut>(options: InferenceResourceOptions<TIn, TOut>): ResourceRef<TOut | undefined>;
+
 /** Minimal recorder surface - lets tests (and exotic runtimes) inject fakes. */
 interface RecorderLike {
     start(): void;
@@ -397,7 +596,8 @@ declare function createMicRecorder(deps?: MicRecorderDeps): MicRecorder;
 
 /**
  * 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
@@ -409,10 +609,12 @@ declare class ModelProgressComponent {
     progress: _angular_core.InputSignal<ModelProgress | null>;
     /** Labels per status; override to localize. */
     labels: _angular_core.InputSignal<Partial<Record<PipelineStatus, string>>>;
+    /** The bar follows the whole download when the handle reports it, else the current file. */
+    percent(progress: ModelProgress): number;
     readonly label: _angular_core.Signal<string>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ModelProgressComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<ModelProgressComponent, "ngx-model-progress", never, { "status": { "alias": "status"; "required": true; "isSignal": true; }; "progress": { "alias": "progress"; "required": false; "isSignal": true; }; "labels": { "alias": "labels"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-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 type { ClassificationResult, MicRecorderDeps, ModelProgress, NgxTransformersConfig, PipelineFactory, PipelineLike, PipelineRequest, PipelineStatus, RankedResult, RecorderLike, TranscribeOptions, Transcription, TranscriptionChunk, TransformersDevice, TransformersDtype, TranslateOptions, TranslationHandle, TranslatorOptions, ZeroShotOptions };
+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 };
+export type { ChatMessage, ClassificationResult, GenerateOptions, InferenceResourceOptions, MicRecorderDeps, ModelProgress, NgxTransformersConfig, OverallProgress, PipelineFactory, PipelineLike, PipelineRequest, PipelineStatus, RankedResult, RecorderLike, RunOptions, TranscribeOptions, Transcription, TranscriptionChunk, TransformersDevice, TransformersDtype, TransformersModuleLike, TranslateOptions, TranslationHandle, TranslatorOptions, ZeroShotOptions };