@fgv/ts-extras-transformers 5.1.0-29

package/dist/ts-extras-transformers.d.ts

@@ -0,0 +1,137 @@
+/**
+ * `@fgv/ts-extras-transformers` — Result-integration boundary over `@huggingface/transformers`
+ * (Node-side).
+ *
+ * A thin facade that wraps `@huggingface/transformers` calls in `Result<T>` from `@fgv/ts-utils`,
+ * mirroring the discipline established by `@fgv/ts-extras-webauthn`: one-line `captureAsyncResult`
+ * wrappers around upstream primitives with **no opinionated orchestration** above the boundary.
+ *
+ * **In scope:** `loadPipeline`, `classify`, `classifyAll`, `embed` — the surface needed by the
+ * B-3/B-4a local-classifier and embedding scenarios. `generate` is explicitly deferred until a
+ * concrete consumer use case surfaces (see `phase-b2-result.md`).
+ *
+ * **Explicitly NOT in scope:**
+ * - Pipeline cache / lifecycle management
+ * - Model registry or download management
+ * - GPU/CPU device selection policy
+ * - Quantization selection
+ * - Embedding-store integration
+ * - Classifier label allowlists
+ * - Request batching
+ * - Pipeline dispose semantics
+ *
+ * For any of the above, use `@huggingface/transformers` directly (with `captureAsyncResult` for
+ * your own Result wrapping).
+ *
+ * @packageDocumentation
+ */
+
+import { AllTasks } from '@huggingface/transformers';
+import { FeatureExtractionPipeline } from '@huggingface/transformers';
+import { pipeline } from '@huggingface/transformers';
+import { PipelineType } from '@huggingface/transformers';
+import { PretrainedModelOptions } from '@huggingface/transformers';
+import { Result } from '@fgv/ts-utils';
+import { Tensor } from '@huggingface/transformers';
+import { TextClassificationOutput } from '@huggingface/transformers';
+import { TextClassificationPipeline } from '@huggingface/transformers';
+
+export { AllTasks }
+
+/**
+ * Result-integration wrapper that invokes a `TextClassificationPipeline` on a single text input.
+ * Returns the classification results as a flat `TextClassificationOutput` (array of
+ * `{ label: string; score: number }` entries).
+ *
+ * Callers should retrieve the pipeline via `loadPipeline('text-classification', modelId)` (or the
+ * `'sentiment-analysis'` alias). This helper always passes a single string to the upstream
+ * pipeline and normalises the result to `TextClassificationOutput` so consumers don't need to
+ * handle the `string | string[]` overload union.
+ *
+ * Returns `Promise<Result<TextClassificationOutput>>`; upstream errors (inference failures,
+ * tokenisation errors) are captured as `Failure` with the original message.
+ *
+ * @param classifier - A `TextClassificationPipeline` obtained from `loadPipeline`.
+ * @param text - The text to classify.
+ * @param options - Optional upstream classification options (e.g. `{ top_k: null }` to return
+ *   all labels). Passed through verbatim to the pipeline call.
+ *
+ * @see https://huggingface.co/docs/transformers.js
+ * @public
+ */
+export declare function classify(classifier: TextClassificationPipeline, text: string, options?: Parameters<TextClassificationPipeline>[1]): Promise<Result<TextClassificationOutput>>;
+
+/**
+ * Convenience wrapper over `classify` that forces `top_k: null` so the full per-label vector
+ * is returned for every call. Callers no longer need to remember to pass `{ top_k: null }`.
+ *
+ * Any caller-supplied options are honoured except `top_k`, which is always overridden to `null`.
+ *
+ * Returns `Promise<Result<TextClassificationOutput>>`; upstream errors are captured as `Failure`
+ * with the original message.
+ *
+ * @param classifier - A `TextClassificationPipeline` obtained from `loadPipeline`.
+ * @param text - The text to classify.
+ * @param options - Optional upstream classification options. `top_k` is always set to `null`
+ *   regardless of any value supplied here.
+ *
+ * @see https://huggingface.co/docs/transformers.js
+ * @public
+ */
+export declare function classifyAll(classifier: TextClassificationPipeline, text: string, options?: Parameters<TextClassificationPipeline>[1]): Promise<Result<TextClassificationOutput>>;
+
+/**
+ * Result-integration wrapper that invokes a `FeatureExtractionPipeline` on a text input.
+ * Returns the upstream `Tensor` Result-wrapped — no pooling, normalisation, or reshaping is
+ * applied. Callers receive the raw output and are responsible for any downstream processing.
+ *
+ * Callers should retrieve the extractor via `loadPipeline('feature-extraction', modelId)`.
+ *
+ * Returns `Promise<Result<Tensor>>`; upstream errors (inference failures, tokenisation errors)
+ * are captured as `Failure` with the original message.
+ *
+ * @param extractor - A `FeatureExtractionPipeline` obtained from `loadPipeline`.
+ * @param text - The text (or texts) to embed.
+ * @param options - Optional upstream feature-extraction options (e.g. `pooling`, `normalize`).
+ *   Passed through verbatim to the pipeline call.
+ *
+ * @see https://huggingface.co/docs/transformers.js
+ * @public
+ */
+export declare function embed(extractor: FeatureExtractionPipeline, text: string | string[], options?: Parameters<FeatureExtractionPipeline['_call']>[1]): Promise<Result<Tensor>>;
+
+export { FeatureExtractionPipeline }
+
+/**
+ * Result-integration wrapper around `@huggingface/transformers`'s `pipeline` factory.
+ * Loads a model and returns a ready-to-use pipeline object.
+ *
+ * The returned pipeline is the upstream `AllTasks[T]` instance — consumers retain full access
+ * to the upstream API. Lifecycle management (caching, disposal, GPU/CPU selection) is the
+ * consumer's responsibility.
+ *
+ * Returns `Promise<Result<AllTasks[T]>>`; upstream errors (network, model-not-found, ONNX
+ * initialization failures) are captured as `Failure` with the original message.
+ *
+ * @param task - The pipeline task type (e.g. `'text-classification'`, `'feature-extraction'`).
+ * @param model - The model identifier (HuggingFace Hub ID or local path). If omitted, the
+ *   upstream default for the task is used.
+ * @param options - Optional `PretrainedModelOptions` (device, dtype, cache_dir, etc.). Passed
+ *   through verbatim to the upstream `pipeline()` call.
+ *
+ * @see https://huggingface.co/docs/transformers.js
+ * @public
+ */
+export declare function loadPipeline<T extends PipelineType>(task: T, model?: string, options?: Parameters<typeof pipeline>[2]): Promise<Result<AllTasks[T]>>;
+
+export { PipelineType }
+
+export { PretrainedModelOptions }
+
+export { Tensor }
+
+export { TextClassificationOutput }
+
+export { TextClassificationPipeline }
+
+export { }

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.7"
+    }
+  ]
+}

package/eslint.config.js

@@ -0,0 +1,15 @@
+// ESLint 9 flat config
+const nodeProfile = require('@rushstack/eslint-config/flat/profile/node');
+const packletsPlugin = require('@rushstack/eslint-config/flat/mixins/packlets');
+const tsdocPlugin = require('@rushstack/eslint-config/flat/mixins/tsdoc');
+
+module.exports = [
+  ...nodeProfile,
+  packletsPlugin,
+  ...tsdocPlugin,
+  {
+    rules: {
+      '@rushstack/packlets/mechanics': 'warn'
+    }
+  }
+];

package/etc/ts-extras-transformers.api.md

@@ -0,0 +1,43 @@
+## API Report File for "@fgv/ts-extras-transformers"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { AllTasks } from '@huggingface/transformers';
+import { FeatureExtractionPipeline } from '@huggingface/transformers';
+import { pipeline } from '@huggingface/transformers';
+import { PipelineType } from '@huggingface/transformers';
+import { PretrainedModelOptions } from '@huggingface/transformers';
+import { Result } from '@fgv/ts-utils';
+import { Tensor } from '@huggingface/transformers';
+import { TextClassificationOutput } from '@huggingface/transformers';
+import { TextClassificationPipeline } from '@huggingface/transformers';
+
+export { AllTasks }
+
+// @public
+export function classify(classifier: TextClassificationPipeline, text: string, options?: Parameters<TextClassificationPipeline>[1]): Promise<Result<TextClassificationOutput>>;
+
+// @public
+export function classifyAll(classifier: TextClassificationPipeline, text: string, options?: Parameters<TextClassificationPipeline>[1]): Promise<Result<TextClassificationOutput>>;
+
+// @public
+export function embed(extractor: FeatureExtractionPipeline, text: string | string[], options?: Parameters<FeatureExtractionPipeline['_call']>[1]): Promise<Result<Tensor>>;
+
+export { FeatureExtractionPipeline }
+
+// @public
+export function loadPipeline<T extends PipelineType>(task: T, model?: string, options?: Parameters<typeof pipeline>[2]): Promise<Result<AllTasks[T]>>;
+
+export { PipelineType }
+
+export { PretrainedModelOptions }
+
+export { Tensor }
+
+export { TextClassificationOutput }
+
+export { TextClassificationPipeline }
+
+```

package/lib/index.d.ts

@@ -0,0 +1,112 @@
+/**
+ * `@fgv/ts-extras-transformers` — Result-integration boundary over `@huggingface/transformers`
+ * (Node-side).
+ *
+ * A thin facade that wraps `@huggingface/transformers` calls in `Result<T>` from `@fgv/ts-utils`,
+ * mirroring the discipline established by `@fgv/ts-extras-webauthn`: one-line `captureAsyncResult`
+ * wrappers around upstream primitives with **no opinionated orchestration** above the boundary.
+ *
+ * **In scope:** `loadPipeline`, `classify`, `classifyAll`, `embed` — the surface needed by the
+ * B-3/B-4a local-classifier and embedding scenarios. `generate` is explicitly deferred until a
+ * concrete consumer use case surfaces (see `phase-b2-result.md`).
+ *
+ * **Explicitly NOT in scope:**
+ * - Pipeline cache / lifecycle management
+ * - Model registry or download management
+ * - GPU/CPU device selection policy
+ * - Quantization selection
+ * - Embedding-store integration
+ * - Classifier label allowlists
+ * - Request batching
+ * - Pipeline dispose semantics
+ *
+ * For any of the above, use `@huggingface/transformers` directly (with `captureAsyncResult` for
+ * your own Result wrapping).
+ *
+ * @packageDocumentation
+ */
+import { pipeline as _pipeline, type TextClassificationPipeline, type TextClassificationOutput, type FeatureExtractionPipeline, type Tensor, type AllTasks, type PipelineType } from '@huggingface/transformers';
+import { type Result } from '@fgv/ts-utils';
+export type { TextClassificationPipeline, TextClassificationOutput, FeatureExtractionPipeline, Tensor, AllTasks, PipelineType };
+export type { PretrainedModelOptions } from '@huggingface/transformers';
+/**
+ * Result-integration wrapper around `@huggingface/transformers`'s `pipeline` factory.
+ * Loads a model and returns a ready-to-use pipeline object.
+ *
+ * The returned pipeline is the upstream `AllTasks[T]` instance — consumers retain full access
+ * to the upstream API. Lifecycle management (caching, disposal, GPU/CPU selection) is the
+ * consumer's responsibility.
+ *
+ * Returns `Promise<Result<AllTasks[T]>>`; upstream errors (network, model-not-found, ONNX
+ * initialization failures) are captured as `Failure` with the original message.
+ *
+ * @param task - The pipeline task type (e.g. `'text-classification'`, `'feature-extraction'`).
+ * @param model - The model identifier (HuggingFace Hub ID or local path). If omitted, the
+ *   upstream default for the task is used.
+ * @param options - Optional `PretrainedModelOptions` (device, dtype, cache_dir, etc.). Passed
+ *   through verbatim to the upstream `pipeline()` call.
+ *
+ * @see https://huggingface.co/docs/transformers.js
+ * @public
+ */
+export declare function loadPipeline<T extends PipelineType>(task: T, model?: string, options?: Parameters<typeof _pipeline>[2]): Promise<Result<AllTasks[T]>>;
+/**
+ * Result-integration wrapper that invokes a `TextClassificationPipeline` on a single text input.
+ * Returns the classification results as a flat `TextClassificationOutput` (array of
+ * `{ label: string; score: number }` entries).
+ *
+ * Callers should retrieve the pipeline via `loadPipeline('text-classification', modelId)` (or the
+ * `'sentiment-analysis'` alias). This helper always passes a single string to the upstream
+ * pipeline and normalises the result to `TextClassificationOutput` so consumers don't need to
+ * handle the `string | string[]` overload union.
+ *
+ * Returns `Promise<Result<TextClassificationOutput>>`; upstream errors (inference failures,
+ * tokenisation errors) are captured as `Failure` with the original message.
+ *
+ * @param classifier - A `TextClassificationPipeline` obtained from `loadPipeline`.
+ * @param text - The text to classify.
+ * @param options - Optional upstream classification options (e.g. `{ top_k: null }` to return
+ *   all labels). Passed through verbatim to the pipeline call.
+ *
+ * @see https://huggingface.co/docs/transformers.js
+ * @public
+ */
+export declare function classify(classifier: TextClassificationPipeline, text: string, options?: Parameters<TextClassificationPipeline>[1]): Promise<Result<TextClassificationOutput>>;
+/**
+ * Convenience wrapper over `classify` that forces `top_k: null` so the full per-label vector
+ * is returned for every call. Callers no longer need to remember to pass `{ top_k: null }`.
+ *
+ * Any caller-supplied options are honoured except `top_k`, which is always overridden to `null`.
+ *
+ * Returns `Promise<Result<TextClassificationOutput>>`; upstream errors are captured as `Failure`
+ * with the original message.
+ *
+ * @param classifier - A `TextClassificationPipeline` obtained from `loadPipeline`.
+ * @param text - The text to classify.
+ * @param options - Optional upstream classification options. `top_k` is always set to `null`
+ *   regardless of any value supplied here.
+ *
+ * @see https://huggingface.co/docs/transformers.js
+ * @public
+ */
+export declare function classifyAll(classifier: TextClassificationPipeline, text: string, options?: Parameters<TextClassificationPipeline>[1]): Promise<Result<TextClassificationOutput>>;
+/**
+ * Result-integration wrapper that invokes a `FeatureExtractionPipeline` on a text input.
+ * Returns the upstream `Tensor` Result-wrapped — no pooling, normalisation, or reshaping is
+ * applied. Callers receive the raw output and are responsible for any downstream processing.
+ *
+ * Callers should retrieve the extractor via `loadPipeline('feature-extraction', modelId)`.
+ *
+ * Returns `Promise<Result<Tensor>>`; upstream errors (inference failures, tokenisation errors)
+ * are captured as `Failure` with the original message.
+ *
+ * @param extractor - A `FeatureExtractionPipeline` obtained from `loadPipeline`.
+ * @param text - The text (or texts) to embed.
+ * @param options - Optional upstream feature-extraction options (e.g. `pooling`, `normalize`).
+ *   Passed through verbatim to the pipeline call.
+ *
+ * @see https://huggingface.co/docs/transformers.js
+ * @public
+ */
+export declare function embed(extractor: FeatureExtractionPipeline, text: string | string[], options?: Parameters<FeatureExtractionPipeline['_call']>[1]): Promise<Result<Tensor>>;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EACL,QAAQ,IAAI,SAAS,EACrB,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,MAAM,EACX,KAAK,QAAQ,EACb,KAAK,YAAY,EAClB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAsB,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAEhE,YAAY,EACV,0BAA0B,EAC1B,wBAAwB,EACxB,yBAAyB,EACzB,MAAM,EACN,QAAQ,EACR,YAAY,EACb,CAAC;AAEF,YAAY,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAExE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,YAAY,CAAC,CAAC,SAAS,YAAY,EACvD,IAAI,EAAE,CAAC,EACP,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,GACxC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAE9B;AAqBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,QAAQ,CAC5B,UAAU,EAAE,0BAA0B,EACtC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,UAAU,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,GAClD,OAAO,CAAC,MAAM,CAAC,wBAAwB,CAAC,CAAC,CAK3C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,0BAA0B,EACtC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,UAAU,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,GAClD,OAAO,CAAC,MAAM,CAAC,wBAAwB,CAAC,CAAC,CAE3C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,KAAK,CACzB,SAAS,EAAE,yBAAyB,EACpC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EACvB,OAAO,CAAC,EAAE,UAAU,CAAC,yBAAyB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,GAC1D,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAEzB"}

package/lib/index.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * `@fgv/ts-extras-transformers` — Result-integration boundary over `@huggingface/transformers`
+ * (Node-side).
+ *
+ * A thin facade that wraps `@huggingface/transformers` calls in `Result<T>` from `@fgv/ts-utils`,
+ * mirroring the discipline established by `@fgv/ts-extras-webauthn`: one-line `captureAsyncResult`
+ * wrappers around upstream primitives with **no opinionated orchestration** above the boundary.
+ *
+ * **In scope:** `loadPipeline`, `classify`, `classifyAll`, `embed` — the surface needed by the
+ * B-3/B-4a local-classifier and embedding scenarios. `generate` is explicitly deferred until a
+ * concrete consumer use case surfaces (see `phase-b2-result.md`).
+ *
+ * **Explicitly NOT in scope:**
+ * - Pipeline cache / lifecycle management
+ * - Model registry or download management
+ * - GPU/CPU device selection policy
+ * - Quantization selection
+ * - Embedding-store integration
+ * - Classifier label allowlists
+ * - Request batching
+ * - Pipeline dispose semantics
+ *
+ * For any of the above, use `@huggingface/transformers` directly (with `captureAsyncResult` for
+ * your own Result wrapping).
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadPipeline = loadPipeline;
+exports.classify = classify;
+exports.classifyAll = classifyAll;
+exports.embed = embed;
+const transformers_1 = require("@huggingface/transformers");
+const ts_utils_1 = require("@fgv/ts-utils");
+/**
+ * Result-integration wrapper around `@huggingface/transformers`'s `pipeline` factory.
+ * Loads a model and returns a ready-to-use pipeline object.
+ *
+ * The returned pipeline is the upstream `AllTasks[T]` instance — consumers retain full access
+ * to the upstream API. Lifecycle management (caching, disposal, GPU/CPU selection) is the
+ * consumer's responsibility.
+ *
+ * Returns `Promise<Result<AllTasks[T]>>`; upstream errors (network, model-not-found, ONNX
+ * initialization failures) are captured as `Failure` with the original message.
+ *
+ * @param task - The pipeline task type (e.g. `'text-classification'`, `'feature-extraction'`).
+ * @param model - The model identifier (HuggingFace Hub ID or local path). If omitted, the
+ *   upstream default for the task is used.
+ * @param options - Optional `PretrainedModelOptions` (device, dtype, cache_dir, etc.). Passed
+ *   through verbatim to the upstream `pipeline()` call.
+ *
+ * @see https://huggingface.co/docs/transformers.js
+ * @public
+ */
+async function loadPipeline(task, model, options) {
+    return (0, ts_utils_1.captureAsyncResult)(() => (0, transformers_1.pipeline)(task, model, options));
+}
+/**
+ * Normalises the upstream pipeline's output to a flat `TextClassificationOutput`.
+ *
+ * The upstream `TextClassificationPipeline` has an overloaded call signature: a single-string
+ * input returns `TextClassificationOutput` (flat array), while a string-array input returns
+ * `TextClassificationOutput[]` (array-of-arrays). Since `classify` always passes a single
+ * string, the flat-array path is the live path. The nested-array branch is defensive and
+ * ensures consumers always receive a flat array even if the upstream type union leaks through.
+ */
+function flattenIfNeeded(result) {
+    if (Array.isArray(result) && result.length > 0 && !Array.isArray(result[0])) {
+        return result;
+    }
+    // Defensive: if somehow an array-of-arrays came back, flatten one level.
+    return result.flat();
+}
+/**
+ * Result-integration wrapper that invokes a `TextClassificationPipeline` on a single text input.
+ * Returns the classification results as a flat `TextClassificationOutput` (array of
+ * `{ label: string; score: number }` entries).
+ *
+ * Callers should retrieve the pipeline via `loadPipeline('text-classification', modelId)` (or the
+ * `'sentiment-analysis'` alias). This helper always passes a single string to the upstream
+ * pipeline and normalises the result to `TextClassificationOutput` so consumers don't need to
+ * handle the `string | string[]` overload union.
+ *
+ * Returns `Promise<Result<TextClassificationOutput>>`; upstream errors (inference failures,
+ * tokenisation errors) are captured as `Failure` with the original message.
+ *
+ * @param classifier - A `TextClassificationPipeline` obtained from `loadPipeline`.
+ * @param text - The text to classify.
+ * @param options - Optional upstream classification options (e.g. `{ top_k: null }` to return
+ *   all labels). Passed through verbatim to the pipeline call.
+ *
+ * @see https://huggingface.co/docs/transformers.js
+ * @public
+ */
+async function classify(classifier, text, options) {
+    return (0, ts_utils_1.captureAsyncResult)(async () => {
+        const result = await classifier(text, options);
+        return flattenIfNeeded(result);
+    });
+}
+/**
+ * Convenience wrapper over `classify` that forces `top_k: null` so the full per-label vector
+ * is returned for every call. Callers no longer need to remember to pass `{ top_k: null }`.
+ *
+ * Any caller-supplied options are honoured except `top_k`, which is always overridden to `null`.
+ *
+ * Returns `Promise<Result<TextClassificationOutput>>`; upstream errors are captured as `Failure`
+ * with the original message.
+ *
+ * @param classifier - A `TextClassificationPipeline` obtained from `loadPipeline`.
+ * @param text - The text to classify.
+ * @param options - Optional upstream classification options. `top_k` is always set to `null`
+ *   regardless of any value supplied here.
+ *
+ * @see https://huggingface.co/docs/transformers.js
+ * @public
+ */
+async function classifyAll(classifier, text, options) {
+    return classify(classifier, text, Object.assign(Object.assign({}, options), { top_k: null }));
+}
+/**
+ * Result-integration wrapper that invokes a `FeatureExtractionPipeline` on a text input.
+ * Returns the upstream `Tensor` Result-wrapped — no pooling, normalisation, or reshaping is
+ * applied. Callers receive the raw output and are responsible for any downstream processing.
+ *
+ * Callers should retrieve the extractor via `loadPipeline('feature-extraction', modelId)`.
+ *
+ * Returns `Promise<Result<Tensor>>`; upstream errors (inference failures, tokenisation errors)
+ * are captured as `Failure` with the original message.
+ *
+ * @param extractor - A `FeatureExtractionPipeline` obtained from `loadPipeline`.
+ * @param text - The text (or texts) to embed.
+ * @param options - Optional upstream feature-extraction options (e.g. `pooling`, `normalize`).
+ *   Passed through verbatim to the pipeline call.
+ *
+ * @see https://huggingface.co/docs/transformers.js
+ * @public
+ */
+async function embed(extractor, text, options) {
+    return (0, ts_utils_1.captureAsyncResult)(() => extractor(text, options));
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;AA4CH,oCAMC;AA0CD,4BASC;AAmBD,kCAMC;AAoBD,sBAMC;AAtJD,4DAQmC;AACnC,4CAAgE;AAahE;;;;;;;;;;;;;;;;;;;GAmBG;AACI,KAAK,UAAU,YAAY,CAChC,IAAO,EACP,KAAc,EACd,OAAyC;IAEzC,OAAO,IAAA,6BAAkB,EAAC,GAAG,EAAE,CAAC,IAAA,uBAAS,EAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,eAAe,CACtB,MAA6D;IAE7D,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,OAAO,MAAkC,CAAC;IAC5C,CAAC;IACD,yEAAyE;IACzE,OAAQ,MAAgD,CAAC,IAAI,EAAE,CAAC;AAClE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACI,KAAK,UAAU,QAAQ,CAC5B,UAAsC,EACtC,IAAY,EACZ,OAAmD;IAEnD,OAAO,IAAA,6BAAkB,EAAC,KAAK,IAAI,EAAE;QACnC,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC/C,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACI,KAAK,UAAU,WAAW,CAC/B,UAAsC,EACtC,IAAY,EACZ,OAAmD;IAEnD,OAAO,QAAQ,CAAC,UAAU,EAAE,IAAI,kCAAO,OAAO,KAAE,KAAK,EAAE,IAAI,IAAG,CAAC;AACjE,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACI,KAAK,UAAU,KAAK,CACzB,SAAoC,EACpC,IAAuB,EACvB,OAA2D;IAE3D,OAAO,IAAA,6BAAkB,EAAC,GAAG,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;AAC5D,CAAC","sourcesContent":["/**\n * `@fgv/ts-extras-transformers` — Result-integration boundary over `@huggingface/transformers`\n * (Node-side).\n *\n * A thin facade that wraps `@huggingface/transformers` calls in `Result<T>` from `@fgv/ts-utils`,\n * mirroring the discipline established by `@fgv/ts-extras-webauthn`: one-line `captureAsyncResult`\n * wrappers around upstream primitives with **no opinionated orchestration** above the boundary.\n *\n * **In scope:** `loadPipeline`, `classify`, `classifyAll`, `embed` — the surface needed by the\n * B-3/B-4a local-classifier and embedding scenarios. `generate` is explicitly deferred until a\n * concrete consumer use case surfaces (see `phase-b2-result.md`).\n *\n * **Explicitly NOT in scope:**\n * - Pipeline cache / lifecycle management\n * - Model registry or download management\n * - GPU/CPU device selection policy\n * - Quantization selection\n * - Embedding-store integration\n * - Classifier label allowlists\n * - Request batching\n * - Pipeline dispose semantics\n *\n * For any of the above, use `@huggingface/transformers` directly (with `captureAsyncResult` for\n * your own Result wrapping).\n *\n * @packageDocumentation\n */\n\nimport {\n  pipeline as _pipeline,\n  type TextClassificationPipeline,\n  type TextClassificationOutput,\n  type FeatureExtractionPipeline,\n  type Tensor,\n  type AllTasks,\n  type PipelineType\n} from '@huggingface/transformers';\nimport { captureAsyncResult, type Result } from '@fgv/ts-utils';\n\nexport type {\n  TextClassificationPipeline,\n  TextClassificationOutput,\n  FeatureExtractionPipeline,\n  Tensor,\n  AllTasks,\n  PipelineType\n};\n\nexport type { PretrainedModelOptions } from '@huggingface/transformers';\n\n/**\n * Result-integration wrapper around `@huggingface/transformers`'s `pipeline` factory.\n * Loads a model and returns a ready-to-use pipeline object.\n *\n * The returned pipeline is the upstream `AllTasks[T]` instance — consumers retain full access\n * to the upstream API. Lifecycle management (caching, disposal, GPU/CPU selection) is the\n * consumer's responsibility.\n *\n * Returns `Promise<Result<AllTasks[T]>>`; upstream errors (network, model-not-found, ONNX\n * initialization failures) are captured as `Failure` with the original message.\n *\n * @param task - The pipeline task type (e.g. `'text-classification'`, `'feature-extraction'`).\n * @param model - The model identifier (HuggingFace Hub ID or local path). If omitted, the\n *   upstream default for the task is used.\n * @param options - Optional `PretrainedModelOptions` (device, dtype, cache_dir, etc.). Passed\n *   through verbatim to the upstream `pipeline()` call.\n *\n * @see https://huggingface.co/docs/transformers.js\n * @public\n */\nexport async function loadPipeline<T extends PipelineType>(\n  task: T,\n  model?: string,\n  options?: Parameters<typeof _pipeline>[2]\n): Promise<Result<AllTasks[T]>> {\n  return captureAsyncResult(() => _pipeline(task, model, options));\n}\n\n/**\n * Normalises the upstream pipeline's output to a flat `TextClassificationOutput`.\n *\n * The upstream `TextClassificationPipeline` has an overloaded call signature: a single-string\n * input returns `TextClassificationOutput` (flat array), while a string-array input returns\n * `TextClassificationOutput[]` (array-of-arrays). Since `classify` always passes a single\n * string, the flat-array path is the live path. The nested-array branch is defensive and\n * ensures consumers always receive a flat array even if the upstream type union leaks through.\n */\nfunction flattenIfNeeded(\n  result: TextClassificationOutput | TextClassificationOutput[]\n): TextClassificationOutput {\n  if (Array.isArray(result) && result.length > 0 && !Array.isArray(result[0])) {\n    return result as TextClassificationOutput;\n  }\n  // Defensive: if somehow an array-of-arrays came back, flatten one level.\n  return (result as unknown as TextClassificationOutput[]).flat();\n}\n\n/**\n * Result-integration wrapper that invokes a `TextClassificationPipeline` on a single text input.\n * Returns the classification results as a flat `TextClassificationOutput` (array of\n * `{ label: string; score: number }` entries).\n *\n * Callers should retrieve the pipeline via `loadPipeline('text-classification', modelId)` (or the\n * `'sentiment-analysis'` alias). This helper always passes a single string to the upstream\n * pipeline and normalises the result to `TextClassificationOutput` so consumers don't need to\n * handle the `string | string[]` overload union.\n *\n * Returns `Promise<Result<TextClassificationOutput>>`; upstream errors (inference failures,\n * tokenisation errors) are captured as `Failure` with the original message.\n *\n * @param classifier - A `TextClassificationPipeline` obtained from `loadPipeline`.\n * @param text - The text to classify.\n * @param options - Optional upstream classification options (e.g. `{ top_k: null }` to return\n *   all labels). Passed through verbatim to the pipeline call.\n *\n * @see https://huggingface.co/docs/transformers.js\n * @public\n */\nexport async function classify(\n  classifier: TextClassificationPipeline,\n  text: string,\n  options?: Parameters<TextClassificationPipeline>[1]\n): Promise<Result<TextClassificationOutput>> {\n  return captureAsyncResult(async () => {\n    const result = await classifier(text, options);\n    return flattenIfNeeded(result);\n  });\n}\n\n/**\n * Convenience wrapper over `classify` that forces `top_k: null` so the full per-label vector\n * is returned for every call. Callers no longer need to remember to pass `{ top_k: null }`.\n *\n * Any caller-supplied options are honoured except `top_k`, which is always overridden to `null`.\n *\n * Returns `Promise<Result<TextClassificationOutput>>`; upstream errors are captured as `Failure`\n * with the original message.\n *\n * @param classifier - A `TextClassificationPipeline` obtained from `loadPipeline`.\n * @param text - The text to classify.\n * @param options - Optional upstream classification options. `top_k` is always set to `null`\n *   regardless of any value supplied here.\n *\n * @see https://huggingface.co/docs/transformers.js\n * @public\n */\nexport async function classifyAll(\n  classifier: TextClassificationPipeline,\n  text: string,\n  options?: Parameters<TextClassificationPipeline>[1]\n): Promise<Result<TextClassificationOutput>> {\n  return classify(classifier, text, { ...options, top_k: null });\n}\n\n/**\n * Result-integration wrapper that invokes a `FeatureExtractionPipeline` on a text input.\n * Returns the upstream `Tensor` Result-wrapped — no pooling, normalisation, or reshaping is\n * applied. Callers receive the raw output and are responsible for any downstream processing.\n *\n * Callers should retrieve the extractor via `loadPipeline('feature-extraction', modelId)`.\n *\n * Returns `Promise<Result<Tensor>>`; upstream errors (inference failures, tokenisation errors)\n * are captured as `Failure` with the original message.\n *\n * @param extractor - A `FeatureExtractionPipeline` obtained from `loadPipeline`.\n * @param text - The text (or texts) to embed.\n * @param options - Optional upstream feature-extraction options (e.g. `pooling`, `normalize`).\n *   Passed through verbatim to the pipeline call.\n *\n * @see https://huggingface.co/docs/transformers.js\n * @public\n */\nexport async function embed(\n  extractor: FeatureExtractionPipeline,\n  text: string | string[],\n  options?: Parameters<FeatureExtractionPipeline['_call']>[1]\n): Promise<Result<Tensor>> {\n  return captureAsyncResult(() => extractor(text, options));\n}\n"]}

package/lib/test/unit/transformers.test.d.ts

@@ -0,0 +1,2 @@
+import '@fgv/ts-utils-jest';
+//# sourceMappingURL=transformers.test.d.ts.map

package/lib/test/unit/transformers.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformers.test.d.ts","sourceRoot":"","sources":["../../../src/test/unit/transformers.test.ts"],"names":[],"mappings":"AAEA,OAAO,oBAAoB,CAAC"}