@fgv/ts-extras-transformers 5.1.0-29

package/CHANGELOG.json

@@ -0,0 +1,4 @@
+{
+  "name": "@fgv/ts-extras-transformers",
+  "entries": []
+}

package/README.md

@@ -0,0 +1,121 @@
+# @fgv/ts-extras-transformers
+
+Result-integration boundary over [`@huggingface/transformers`](https://huggingface.co/docs/transformers.js/en/index)
+for Node-side consumers. The companion package
+[`@fgv/ts-web-extras-transformers`](../ts-web-extras-transformers) provides the same surface for
+browser consumers.
+
+**Status:** shipped — the `local-ai-exploration` done-or-discard gate decided to ship this facade.
+
+---
+
+## What this is
+
+A thin facade that wraps `@huggingface/transformers` calls in `Result<T>` from `@fgv/ts-utils`,
+mirroring the discipline established by
+[`@fgv/ts-extras-webauthn`](../ts-extras-webauthn): one-line `captureAsyncResult` wrappers around
+upstream primitives with **no opinionated orchestration** above the boundary. Consumers compose
+the primitives into their own pipelines.
+
+## Explicitly NOT in scope
+
+These items were considered and explicitly deferred — use `@huggingface/transformers` directly
+(with `captureAsyncResult` for your own Result wrapping) for any of them:
+
+- 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
+
+## Four primitives. Nothing else.
+
+| Function | Return | Wraps |
+|---|---|---|
+| `loadPipeline(task, model?, options?)` | `Promise<Result<AllTasks[T]>>` | `pipeline()` |
+| `classify(pipeline, text, options?)` | `Promise<Result<TextClassificationOutput>>` | `TextClassificationPipeline` call |
+| `classifyAll(pipeline, text, options?)` | `Promise<Result<TextClassificationOutput>>` | `classify` with `top_k: null` forced |
+| `embed(extractor, text, options?)` | `Promise<Result<Tensor>>` | `FeatureExtractionPipeline` call |
+
+**Deferred (not in scope):**
+
+| Function | Rationale |
+|---|---|
+| `generate(pipeline, text, options?)` | No concrete consumer use case; text-generation output shape is more complex (single/batch/chat variants). Defer until a scenario exercises it. |
+
+---
+
+## Usage
+
+```typescript
+import { loadPipeline, classify } from '@fgv/ts-extras-transformers';
+import { fail, succeed } from '@fgv/ts-utils';
+
+// Load a sentiment-analysis model (wraps @huggingface/transformers pipeline()).
+// The pipeline object is the upstream AllTasks['text-classification'] instance.
+// Lifecycle management (caching, disposal, device selection) is your responsibility.
+const classifierResult = await loadPipeline(
+  'text-classification',
+  'Xenova/distilbert-base-uncased-finetuned-sst-2-english'
+);
+if (classifierResult.isFailure()) {
+  // Model load failed (network error, ONNX init failure, model-not-found, etc.)
+  console.error(classifierResult.message);
+  return;
+}
+
+const classifier = classifierResult.value;
+
+// Classify a single text input.
+const result = await classify(classifier, 'I love transformers!');
+if (result.isSuccess()) {
+  // [{ label: 'POSITIVE', score: 0.9998 }]
+  console.log(result.value);
+}
+
+// Pass upstream options through verbatim:
+const allLabels = await classify(classifier, 'I love transformers!', { top_k: null });
+
+// Compose naturally in a Result chain:
+const screenedResult = await loadPipeline('text-classification', modelId)
+  .then(r => r.onSuccess(async (pipe) => classify(pipe, userInput)))
+  .then(r => r.onSuccess(labels => {
+    const topLabel = labels[0];
+    if (topLabel.label === 'UNSAFE' && topLabel.score > 0.9) {
+      return fail('Content safety screen rejected the input');
+    }
+    return succeed(userInput);
+  }));
+```
+
+---
+
+## Runtime requirements
+
+- **Node.js:** v20 LTS or later (ONNX runtime native binding requirement)
+- **`@huggingface/transformers`:** ^4.2.0 (peer dependency; bring your own)
+- **`@fgv/ts-utils`:** workspace:* (peer dependency)
+
+Model weights are downloaded from the HuggingFace Hub on first use and cached to disk
+(`~/.cache/huggingface/` by default). Pass `cache_dir` in `options` to change the cache
+location. The upstream library manages the download lifecycle; this facade does not.
+
+---
+
+## Notes on `skipLibCheck`
+
+This package sets `skipLibCheck: true` in its `tsconfig.json`. The `@huggingface/transformers`
+v4.x type definitions contain internal type errors in transitive dependencies
+(`@huggingface/tokenizers` path aliases, `Float16Array` missing from ES2018 lib,
+`MgpstrProcessor` method signature mismatch). These are upstream issues — not errors in this
+package's own code. `skipLibCheck` silences them without affecting type safety at this package's
+own boundary.
+
+---
+
+## License
+
+MIT — same as the parent fgv monorepo. `@huggingface/transformers` is Apache-2.0.

package/config/api-extractor.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "projectFolder": "..",
+  "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",
+  "bundledPackages": [],
+  "compiler": {},
+  "apiReport": {
+    "enabled": true
+  },
+  "docModel": {
+    "enabled": true
+  },
+  "dtsRollup": {
+    "enabled": true
+  },
+  "tsdocMetadata": {},
+  "messages": {
+    "compilerMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      }
+    },
+    "extractorMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      },
+      "ae-unresolved-link": {
+        "logLevel": "none",
+        "addToApiReportFile": true
+      }
+    },
+    "tsdocMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      }
+    }
+  }
+}

package/config/jest.config.json

@@ -0,0 +1,13 @@
+{
+  "extends": "@rushstack/heft-node-rig/profiles/default/config/jest.config.json",
+  "coverageThreshold": {
+    "global": {
+      "branches": 100,
+      "functions": 100,
+      "lines": 100,
+      "statements": 100
+    }
+  },
+  "collectCoverage": true,
+  "coverageReporters": ["text", "lcov", "html"]
+}

package/config/rig.json

@@ -0,0 +1,6 @@
+// The "rig.json" file directs tools to look for their config files in an external package.
+// Documentation for this system: https://www.npmjs.com/package/@rushstack/rig-package
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+  "rigPackageName": "@fgv/heft-dual-rig"
+}

package/dist/index.js

@@ -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 { pipeline as _pipeline } from '@huggingface/transformers';
+import { captureAsyncResult } from '@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
+ */
+export async function loadPipeline(task, model, options) {
+    return captureAsyncResult(() => _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
+ */
+export async function classify(classifier, text, options) {
+    return 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
+ */
+export 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
+ */
+export async function embed(extractor, text, options) {
+    return captureAsyncResult(() => extractor(text, options));
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EACL,QAAQ,IAAI,SAAS,EAOtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,kBAAkB,EAAe,MAAM,eAAe,CAAC;AAahE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAO,EACP,KAAc,EACd,OAAyC;IAEzC,OAAO,kBAAkB,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,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;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,UAAsC,EACtC,IAAY,EACZ,OAAmD;IAEnD,OAAO,kBAAkB,CAAC,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;AACH,MAAM,CAAC,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;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,SAAoC,EACpC,IAAuB,EACvB,OAA2D;IAE3D,OAAO,kBAAkB,CAAC,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/dist/test/unit/transformers.test.js

@@ -0,0 +1,197 @@
+jest.mock('@huggingface/transformers');
+import '@fgv/ts-utils-jest';
+import * as upstream from '@huggingface/transformers';
+import { loadPipeline, classify, classifyAll, embed } from '../../index';
+// ─── loadPipeline ──────────────────────────────────────────────────────────────
+describe('loadPipeline', () => {
+    beforeEach(() => {
+        jest.resetAllMocks();
+    });
+    test('returns Success wrapping the upstream pipeline on success', async () => {
+        const mockPipeline = jest.fn();
+        jest.mocked(upstream.pipeline).mockResolvedValueOnce(mockPipeline);
+        const result = await loadPipeline('text-classification', 'Xenova/distilbert-base-uncased-finetuned-sst-2-english');
+        expect(result).toSucceedWith(mockPipeline);
+    });
+    test('passes task and model to the upstream pipeline factory', async () => {
+        const mockPipeline = jest.fn();
+        jest.mocked(upstream.pipeline).mockResolvedValueOnce(mockPipeline);
+        await loadPipeline('text-classification', 'some-model-id');
+        expect(upstream.pipeline).toHaveBeenCalledWith('text-classification', 'some-model-id', undefined);
+    });
+    test('passes options through to the upstream pipeline factory', async () => {
+        const mockPipeline = jest.fn();
+        jest.mocked(upstream.pipeline).mockResolvedValueOnce(mockPipeline);
+        const opts = { device: 'cpu' };
+        await loadPipeline('text-classification', 'some-model-id', opts);
+        expect(upstream.pipeline).toHaveBeenCalledWith('text-classification', 'some-model-id', opts);
+    });
+    test('returns Success when model is omitted', async () => {
+        const mockPipeline = jest.fn();
+        jest.mocked(upstream.pipeline).mockResolvedValueOnce(mockPipeline);
+        const result = await loadPipeline('feature-extraction');
+        expect(result).toSucceed();
+        expect(upstream.pipeline).toHaveBeenCalledWith('feature-extraction', undefined, undefined);
+    });
+    test('returns Failure capturing upstream error message on network failure', async () => {
+        jest
+            .mocked(upstream.pipeline)
+            .mockRejectedValueOnce(new Error('Could not locate the model: model-not-found'));
+        const result = await loadPipeline('text-classification', 'model-not-found');
+        expect(result).toFailWith(/could not locate the model/i);
+    });
+    test('returns Failure capturing upstream error on ONNX init failure', async () => {
+        jest.mocked(upstream.pipeline).mockRejectedValueOnce(new Error('Failed to initialize ONNX runtime'));
+        const result = await loadPipeline('text-classification', 'some-model');
+        expect(result).toFailWith(/failed to initialize onnx runtime/i);
+    });
+});
+// ─── classify ─────────────────────────────────────────────────────────────────
+describe('classify', () => {
+    let mockClassifier;
+    beforeEach(() => {
+        jest.resetAllMocks();
+        mockClassifier = jest.fn();
+    });
+    test('returns Success wrapping TextClassificationOutput on success', async () => {
+        const mockOutput = [{ label: 'POSITIVE', score: 0.9998 }];
+        mockClassifier.mockResolvedValueOnce(mockOutput);
+        const result = await classify(mockClassifier, 'I love transformers!');
+        expect(result).toSucceedWith(mockOutput);
+    });
+    test('passes text to the upstream classifier', async () => {
+        const mockOutput = [{ label: 'NEGATIVE', score: 0.9997 }];
+        mockClassifier.mockResolvedValueOnce(mockOutput);
+        await classify(mockClassifier, 'I hate bugs');
+        expect(mockClassifier).toHaveBeenCalledWith('I hate bugs', undefined);
+    });
+    test('passes options through to the upstream classifier', async () => {
+        const mockOutput = [
+            { label: 'POSITIVE', score: 0.9998 },
+            { label: 'NEGATIVE', score: 0.0002 }
+        ];
+        mockClassifier.mockResolvedValueOnce(mockOutput);
+        const opts = { top_k: null };
+        await classify(mockClassifier, 'Hello world', opts);
+        expect(mockClassifier).toHaveBeenCalledWith('Hello world', opts);
+    });
+    test('normalises flat array result correctly', async () => {
+        const mockOutput = [
+            { label: 'SAFE', score: 0.95 },
+            { label: 'UNSAFE', score: 0.05 }
+        ];
+        mockClassifier.mockResolvedValueOnce(mockOutput);
+        expect(await classify(mockClassifier, 'hello')).toSucceedWith(mockOutput);
+    });
+    test('normalises nested array result by flattening one level', async () => {
+        // When upstream returns array-of-arrays (e.g. batch input path leaked through),
+        // we flatten one level so consumers always receive a flat TextClassificationOutput.
+        const inner = [{ label: 'POSITIVE', score: 0.9 }];
+        mockClassifier.mockResolvedValueOnce([inner]);
+        expect(await classify(mockClassifier, 'hello')).toSucceedAndSatisfy((output) => {
+            expect(output).toEqual([{ label: 'POSITIVE', score: 0.9 }]);
+        });
+    });
+    test('returns Failure capturing upstream error on inference failure', async () => {
+        mockClassifier.mockRejectedValueOnce(new Error('Inference session error: out of memory'));
+        const result = await classify(mockClassifier, 'some text');
+        expect(result).toFailWith(/inference session error/i);
+    });
+    test('returns Failure capturing upstream tokenisation error', async () => {
+        mockClassifier.mockRejectedValueOnce(new Error('Tokenisation failed: unexpected token'));
+        const result = await classify(mockClassifier, 'bad input');
+        expect(result).toFailWith(/tokenisation failed/i);
+    });
+});
+// ─── classifyAll ──────────────────────────────────────────────────────────────
+describe('classifyAll', () => {
+    let mockClassifier;
+    beforeEach(() => {
+        jest.resetAllMocks();
+        mockClassifier = jest.fn();
+    });
+    test('forces top_k: null on the underlying classify call', async () => {
+        const mockOutput = [
+            { label: 'POSITIVE', score: 0.9998 },
+            { label: 'NEGATIVE', score: 0.0002 }
+        ];
+        mockClassifier.mockResolvedValueOnce(mockOutput);
+        await classifyAll(mockClassifier, 'hello');
+        expect(mockClassifier).toHaveBeenCalledWith('hello', { top_k: null });
+    });
+    test('overrides caller-supplied top_k with null', async () => {
+        const mockOutput = [
+            { label: 'POSITIVE', score: 0.9998 },
+            { label: 'NEGATIVE', score: 0.0002 }
+        ];
+        mockClassifier.mockResolvedValueOnce(mockOutput);
+        await classifyAll(mockClassifier, 'hello', { top_k: 1 });
+        expect(mockClassifier).toHaveBeenCalledWith('hello', { top_k: null });
+    });
+    test('returns all labels on success', async () => {
+        const mockOutput = [
+            { label: 'POSITIVE', score: 0.9998 },
+            { label: 'NEGATIVE', score: 0.0002 }
+        ];
+        mockClassifier.mockResolvedValueOnce(mockOutput);
+        const result = await classifyAll(mockClassifier, 'I love transformers!');
+        expect(result).toSucceedWith(mockOutput);
+    });
+    test('propagates upstream inference failure as Failure', async () => {
+        mockClassifier.mockRejectedValueOnce(new Error('Inference session error: out of memory'));
+        const result = await classifyAll(mockClassifier, 'some text');
+        expect(result).toFailWith(/inference session error/i);
+    });
+});
+// ─── embed ────────────────────────────────────────────────────────────────────
+describe('embed', () => {
+    let mockExtractor;
+    beforeEach(() => {
+        jest.resetAllMocks();
+        mockExtractor = jest.fn();
+    });
+    test('returns Success wrapping the upstream Tensor on success', async () => {
+        const mockTensor = {
+            type: 'float32',
+            data: new Float32Array([0.1, 0.2, 0.3]),
+            dims: [1, 3]
+        };
+        mockExtractor.mockResolvedValueOnce(mockTensor);
+        const result = await embed(mockExtractor, 'This is a test.');
+        expect(result).toSucceedWith(mockTensor);
+    });
+    test('passes text to the upstream extractor', async () => {
+        const mockTensor = { type: 'float32', data: new Float32Array([0.1]), dims: [1, 1] };
+        mockExtractor.mockResolvedValueOnce(mockTensor);
+        await embed(mockExtractor, 'hello world');
+        expect(mockExtractor).toHaveBeenCalledWith('hello world', undefined);
+    });
+    test('passes string array to the upstream extractor', async () => {
+        const mockTensor = {
+            type: 'float32',
+            data: new Float32Array([0.1, 0.2]),
+            dims: [2, 1]
+        };
+        mockExtractor.mockResolvedValueOnce(mockTensor);
+        await embed(mockExtractor, ['text one', 'text two']);
+        expect(mockExtractor).toHaveBeenCalledWith(['text one', 'text two'], undefined);
+    });
+    test('passes options through to the upstream extractor', async () => {
+        const mockTensor = { type: 'float32', data: new Float32Array([0.5]), dims: [1, 1] };
+        mockExtractor.mockResolvedValueOnce(mockTensor);
+        const opts = { pooling: 'mean', normalize: true };
+        await embed(mockExtractor, 'some text', opts);
+        expect(mockExtractor).toHaveBeenCalledWith('some text', opts);
+    });
+    test('returns Failure capturing upstream inference error', async () => {
+        mockExtractor.mockRejectedValueOnce(new Error('Inference session error: out of memory'));
+        const result = await embed(mockExtractor, 'some text');
+        expect(result).toFailWith(/inference session error/i);
+    });
+    test('returns Failure capturing upstream tokenisation error', async () => {
+        mockExtractor.mockRejectedValueOnce(new Error('Tokenisation failed: input too long'));
+        const result = await embed(mockExtractor, 'bad input');
+        expect(result).toFailWith(/tokenisation failed/i);
+    });
+});
+//# sourceMappingURL=transformers.test.js.map

package/dist/test/unit/transformers.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformers.test.js","sourceRoot":"","sources":["../../../src/test/unit/transformers.test.ts"],"names":[],"mappings":"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","sourcesContent":["jest.mock('@huggingface/transformers');\n\nimport '@fgv/ts-utils-jest';\nimport * as upstream from '@huggingface/transformers';\nimport {\n  loadPipeline,\n  classify,\n  classifyAll,\n  embed,\n  type TextClassificationPipeline,\n  type TextClassificationOutput,\n  type FeatureExtractionPipeline,\n  type Tensor,\n  type AllTasks\n} from '../../index';\n\n// ─── loadPipeline ──────────────────────────────────────────────────────────────\n\ndescribe('loadPipeline', () => {\n  beforeEach(() => {\n    jest.resetAllMocks();\n  });\n\n  test('returns Success wrapping the upstream pipeline on success', async () => {\n    const mockPipeline = jest.fn() as unknown as AllTasks['text-classification'];\n    jest.mocked(upstream.pipeline).mockResolvedValueOnce(mockPipeline);\n\n    const result = await loadPipeline(\n      'text-classification',\n      'Xenova/distilbert-base-uncased-finetuned-sst-2-english'\n    );\n    expect(result).toSucceedWith(mockPipeline);\n  });\n\n  test('passes task and model to the upstream pipeline factory', async () => {\n    const mockPipeline = jest.fn() as unknown as AllTasks['text-classification'];\n    jest.mocked(upstream.pipeline).mockResolvedValueOnce(mockPipeline);\n\n    await loadPipeline('text-classification', 'some-model-id');\n    expect(upstream.pipeline).toHaveBeenCalledWith('text-classification', 'some-model-id', undefined);\n  });\n\n  test('passes options through to the upstream pipeline factory', async () => {\n    const mockPipeline = jest.fn() as unknown as AllTasks['text-classification'];\n    jest.mocked(upstream.pipeline).mockResolvedValueOnce(mockPipeline);\n\n    const opts = { device: 'cpu' } as Parameters<typeof upstream.pipeline>[2];\n    await loadPipeline('text-classification', 'some-model-id', opts);\n    expect(upstream.pipeline).toHaveBeenCalledWith('text-classification', 'some-model-id', opts);\n  });\n\n  test('returns Success when model is omitted', async () => {\n    const mockPipeline = jest.fn() as unknown as AllTasks['feature-extraction'];\n    jest.mocked(upstream.pipeline).mockResolvedValueOnce(mockPipeline);\n\n    const result = await loadPipeline('feature-extraction');\n    expect(result).toSucceed();\n    expect(upstream.pipeline).toHaveBeenCalledWith('feature-extraction', undefined, undefined);\n  });\n\n  test('returns Failure capturing upstream error message on network failure', async () => {\n    jest\n      .mocked(upstream.pipeline)\n      .mockRejectedValueOnce(new Error('Could not locate the model: model-not-found'));\n\n    const result = await loadPipeline('text-classification', 'model-not-found');\n    expect(result).toFailWith(/could not locate the model/i);\n  });\n\n  test('returns Failure capturing upstream error on ONNX init failure', async () => {\n    jest.mocked(upstream.pipeline).mockRejectedValueOnce(new Error('Failed to initialize ONNX runtime'));\n\n    const result = await loadPipeline('text-classification', 'some-model');\n    expect(result).toFailWith(/failed to initialize onnx runtime/i);\n  });\n});\n\n// ─── classify ─────────────────────────────────────────────────────────────────\n\ndescribe('classify', () => {\n  let mockClassifier: jest.MockedFunction<TextClassificationPipeline>;\n\n  beforeEach(() => {\n    jest.resetAllMocks();\n    mockClassifier = jest.fn() as unknown as jest.MockedFunction<TextClassificationPipeline>;\n  });\n\n  test('returns Success wrapping TextClassificationOutput on success', async () => {\n    const mockOutput: TextClassificationOutput = [{ label: 'POSITIVE', score: 0.9998 }];\n    mockClassifier.mockResolvedValueOnce(mockOutput);\n\n    const result = await classify(mockClassifier, 'I love transformers!');\n    expect(result).toSucceedWith(mockOutput);\n  });\n\n  test('passes text to the upstream classifier', async () => {\n    const mockOutput: TextClassificationOutput = [{ label: 'NEGATIVE', score: 0.9997 }];\n    mockClassifier.mockResolvedValueOnce(mockOutput);\n\n    await classify(mockClassifier, 'I hate bugs');\n    expect(mockClassifier).toHaveBeenCalledWith('I hate bugs', undefined);\n  });\n\n  test('passes options through to the upstream classifier', async () => {\n    const mockOutput: TextClassificationOutput = [\n      { label: 'POSITIVE', score: 0.9998 },\n      { label: 'NEGATIVE', score: 0.0002 }\n    ];\n    mockClassifier.mockResolvedValueOnce(mockOutput);\n\n    const opts = { top_k: null };\n    await classify(mockClassifier, 'Hello world', opts);\n    expect(mockClassifier).toHaveBeenCalledWith('Hello world', opts);\n  });\n\n  test('normalises flat array result correctly', async () => {\n    const mockOutput: TextClassificationOutput = [\n      { label: 'SAFE', score: 0.95 },\n      { label: 'UNSAFE', score: 0.05 }\n    ];\n    mockClassifier.mockResolvedValueOnce(mockOutput);\n\n    expect(await classify(mockClassifier, 'hello')).toSucceedWith(mockOutput);\n  });\n\n  test('normalises nested array result by flattening one level', async () => {\n    // When upstream returns array-of-arrays (e.g. batch input path leaked through),\n    // we flatten one level so consumers always receive a flat TextClassificationOutput.\n    const inner: TextClassificationOutput = [{ label: 'POSITIVE', score: 0.9 }];\n    mockClassifier.mockResolvedValueOnce([inner] as unknown as TextClassificationOutput);\n\n    expect(await classify(mockClassifier, 'hello')).toSucceedAndSatisfy((output) => {\n      expect(output).toEqual([{ label: 'POSITIVE', score: 0.9 }]);\n    });\n  });\n\n  test('returns Failure capturing upstream error on inference failure', async () => {\n    mockClassifier.mockRejectedValueOnce(new Error('Inference session error: out of memory'));\n\n    const result = await classify(mockClassifier, 'some text');\n    expect(result).toFailWith(/inference session error/i);\n  });\n\n  test('returns Failure capturing upstream tokenisation error', async () => {\n    mockClassifier.mockRejectedValueOnce(new Error('Tokenisation failed: unexpected token'));\n\n    const result = await classify(mockClassifier, 'bad input');\n    expect(result).toFailWith(/tokenisation failed/i);\n  });\n});\n\n// ─── classifyAll ──────────────────────────────────────────────────────────────\n\ndescribe('classifyAll', () => {\n  let mockClassifier: jest.MockedFunction<TextClassificationPipeline>;\n\n  beforeEach(() => {\n    jest.resetAllMocks();\n    mockClassifier = jest.fn() as unknown as jest.MockedFunction<TextClassificationPipeline>;\n  });\n\n  test('forces top_k: null on the underlying classify call', async () => {\n    const mockOutput: TextClassificationOutput = [\n      { label: 'POSITIVE', score: 0.9998 },\n      { label: 'NEGATIVE', score: 0.0002 }\n    ];\n    mockClassifier.mockResolvedValueOnce(mockOutput);\n\n    await classifyAll(mockClassifier, 'hello');\n    expect(mockClassifier).toHaveBeenCalledWith('hello', { top_k: null });\n  });\n\n  test('overrides caller-supplied top_k with null', async () => {\n    const mockOutput: TextClassificationOutput = [\n      { label: 'POSITIVE', score: 0.9998 },\n      { label: 'NEGATIVE', score: 0.0002 }\n    ];\n    mockClassifier.mockResolvedValueOnce(mockOutput);\n\n    await classifyAll(mockClassifier, 'hello', { top_k: 1 });\n    expect(mockClassifier).toHaveBeenCalledWith('hello', { top_k: null });\n  });\n\n  test('returns all labels on success', async () => {\n    const mockOutput: TextClassificationOutput = [\n      { label: 'POSITIVE', score: 0.9998 },\n      { label: 'NEGATIVE', score: 0.0002 }\n    ];\n    mockClassifier.mockResolvedValueOnce(mockOutput);\n\n    const result = await classifyAll(mockClassifier, 'I love transformers!');\n    expect(result).toSucceedWith(mockOutput);\n  });\n\n  test('propagates upstream inference failure as Failure', async () => {\n    mockClassifier.mockRejectedValueOnce(new Error('Inference session error: out of memory'));\n\n    const result = await classifyAll(mockClassifier, 'some text');\n    expect(result).toFailWith(/inference session error/i);\n  });\n});\n\n// ─── embed ────────────────────────────────────────────────────────────────────\n\ndescribe('embed', () => {\n  let mockExtractor: jest.MockedFunction<FeatureExtractionPipeline>;\n\n  beforeEach(() => {\n    jest.resetAllMocks();\n    mockExtractor = jest.fn() as unknown as jest.MockedFunction<FeatureExtractionPipeline>;\n  });\n\n  test('returns Success wrapping the upstream Tensor on success', async () => {\n    const mockTensor = {\n      type: 'float32',\n      data: new Float32Array([0.1, 0.2, 0.3]),\n      dims: [1, 3]\n    } as unknown as Tensor;\n    mockExtractor.mockResolvedValueOnce(mockTensor);\n\n    const result = await embed(mockExtractor, 'This is a test.');\n    expect(result).toSucceedWith(mockTensor);\n  });\n\n  test('passes text to the upstream extractor', async () => {\n    const mockTensor = { type: 'float32', data: new Float32Array([0.1]), dims: [1, 1] } as unknown as Tensor;\n    mockExtractor.mockResolvedValueOnce(mockTensor);\n\n    await embed(mockExtractor, 'hello world');\n    expect(mockExtractor).toHaveBeenCalledWith('hello world', undefined);\n  });\n\n  test('passes string array to the upstream extractor', async () => {\n    const mockTensor = {\n      type: 'float32',\n      data: new Float32Array([0.1, 0.2]),\n      dims: [2, 1]\n    } as unknown as Tensor;\n    mockExtractor.mockResolvedValueOnce(mockTensor);\n\n    await embed(mockExtractor, ['text one', 'text two']);\n    expect(mockExtractor).toHaveBeenCalledWith(['text one', 'text two'], undefined);\n  });\n\n  test('passes options through to the upstream extractor', async () => {\n    const mockTensor = { type: 'float32', data: new Float32Array([0.5]), dims: [1, 1] } as unknown as Tensor;\n    mockExtractor.mockResolvedValueOnce(mockTensor);\n\n    const opts = { pooling: 'mean' as const, normalize: true };\n    await embed(mockExtractor, 'some text', opts);\n    expect(mockExtractor).toHaveBeenCalledWith('some text', opts);\n  });\n\n  test('returns Failure capturing upstream inference error', async () => {\n    mockExtractor.mockRejectedValueOnce(new Error('Inference session error: out of memory'));\n\n    const result = await embed(mockExtractor, 'some text');\n    expect(result).toFailWith(/inference session error/i);\n  });\n\n  test('returns Failure capturing upstream tokenisation error', async () => {\n    mockExtractor.mockRejectedValueOnce(new Error('Tokenisation failed: input too long'));\n\n    const result = await embed(mockExtractor, 'bad input');\n    expect(result).toFailWith(/tokenisation failed/i);\n  });\n});\n"]}