chore(deps): migrate @xenova/transformers to @huggingface/transformers v4 - #1096
Conversation
|
@aqeelat is attempting to deploy a commit to the rohitg00's projects Team on Vercel. A member of the Team first needs to authorize it. |
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThe PR migrates embedding and reranking integrations from ChangesTransformers package migration
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
src/huggingface.d.ts (1)
1-6: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAvoid broad
any/unknowndeclarations for the optional package.
@huggingface/transformers4.2.0 ships TypeScript declarations, including a typedRawImage.fromBlob(): Promise<RawImage>. This ambient shim widens the APIs toanyandunknown, allowing invalid pipeline options and image handling to compile. Keep only a narrow fallback interface if omitted optional dependencies must still type-check. (npmjs.com)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/huggingface.d.ts` around lines 1 - 6, Update the ambient module declaration for `@huggingface/transformers` to avoid broad any and unknown types, relying on the package’s shipped declarations when available and retaining only a narrow fallback interface if needed for absent optional dependencies. Preserve typed pipeline options and make RawImage.fromBlob return the declared RawImage type.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Line 1267: Update the README description for EMBEDDING_PROVIDER=local to
identify Xenova/all-MiniLM-L6-v2 as the default on-device model instead of
BGE-small, keeping the existing local-embedding behavior and configuration
guidance unchanged.
In `@test/reranker.test.ts`:
- Around line 3-10: Add a second reranker test case with a successful mock of
the `@huggingface/transformers` pipeline, alongside the existing
unavailable-module test. Exercise rerank and assert the mocked pipeline is
invoked or produces a changed ranking, so the test verifies the intended module
is loaded and used.
---
Nitpick comments:
In `@src/huggingface.d.ts`:
- Around line 1-6: Update the ambient module declaration for
`@huggingface/transformers` to avoid broad any and unknown types, relying on the
package’s shipped declarations when available and retaining only a narrow
fallback interface if needed for absent optional dependencies. Preserve typed
pipeline options and make RawImage.fromBlob return the declared RawImage type.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 15cb4830-5d34-4022-87d3-edd1a031e265
📒 Files selected for processing (24)
README.mdREADMEs/README.de-DE.mdREADMEs/README.es-ES.mdREADMEs/README.fr-FR.mdREADMEs/README.hi-IN.mdREADMEs/README.ja-JP.mdREADMEs/README.ko-KR.mdREADMEs/README.pt-BR.mdREADMEs/README.ru-RU.mdREADMEs/README.tr-TR.mdREADMEs/README.zh-CN.mdREADMEs/README.zh-TW.mdSECURITY.mdbenchmark/LONGMEMEVAL.mdbenchmark/REAL-EMBEDDINGS.mdbenchmark/real-embeddings-eval.tspackage.jsonsrc/huggingface.d.tssrc/providers/embedding/clip.tssrc/providers/embedding/local.tssrc/state/reranker.tssrc/xenova.d.tstest/reranker.test.tstsdown.config.ts
💤 Files with no reviewable changes (1)
- src/xenova.d.ts
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@test/reranker.test.ts`:
- Around line 106-107: Make the mock cleanup around the reranker tests
exception-safe by moving vi.doUnmock("`@huggingface/transformers`") into an
afterEach hook or a try/finally block. Keep vi.resetModules() as module-cache
cleanup, and ensure the unmock always runs even when a test assertion fails.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 056f358f-378b-4d83-b869-d6f9298d82ea
📒 Files selected for processing (4)
README.mdsrc/providers/embedding/clip.tssrc/state/reranker.tstest/reranker.test.ts
🚧 Files skipped from review as they are similar to previous changes (2)
- src/state/reranker.ts
- src/providers/embedding/clip.ts
…s v4 @xenova/transformers@2.x is deprecated and silently broken on Node 22+ (see rohitg00#479). The project was renamed to @huggingface/transformers; same Apache-2.0 license, same code. v4 ships onnxruntime-node/web and sharp as hard deps, so they're dropped from our optionalDependencies. Pipeline / RawImage.fromBlob / tolist / text-classification output shape all unchanged. Three behavior-preserving adjustments needed: - All 4 pipeline call sites pass { dtype: "q8" }. v4's default on Node is fp32 (DEFAULT_DEVICE_DTYPE = "fp32"); v2 defaulted to quantized=true. Without explicit dtype, all 4 sites silently regress (~3.5x larger download, slower inference). dtype "q8" maps to model_quantized.onnx per v4's DEFAULT_DTYPE_SUFFIX_MAPPING; file exists in all 3 Xenova models. This was the regression that prompted the test additions below. - src/providers/embedding/local.ts: split import try/catch from pipeline() call so model-load errors (network, missing q8 variant, disk) propagate with their actual message, not masked as "Install @huggingface/transformers...". - src/providers/embedding/{local,clip}.ts: type module from typeof import("@huggingface/transformers") so PretrainedModelOptions flows through; drop hand-rolled aliases and @ts-ignore. Cast at assignment sites (pipeline return union isn't structurally assignable to our narrow FeatureExtractor / ClipPipeline shapes). Tests added where coverage was zero (would have caught the dtype regression): - test/local-embedding-provider.test.ts (3 tests): unavailable-path install hint; pipeline called with dtype:q8 + extractor options + mapped Float32Array result; embedBatch shape. - test/clip-embedding-provider.test.ts (5 tests): unavailable-path; text pipeline dtype:q8 + result; embedBatch; embedImage with data: URL decode; custom model ID propagation. - test/reranker.test.ts: positive-path using vi.doMock + resetModules. Other: - src/huggingface.d.ts deleted (package ships its own types). - src/xenova.d.ts removed. - src/providers/embedding/clip.ts: inline single-use DIMENSIONS constant. - tsdown.config.ts: trim neverBundle list and comment. - README.md L1267: BGE-small -> Xenova/all-MiniLM-L6-v2 (was always wrong). - 16 docs: install commands + prose mentions across main README, 11 translations, SECURITY.md, 2 benchmark docs, benchmark script. - Model IDs (Xenova/all-MiniLM-L6-v2, Xenova/clip-vit-base-patch32, Xenova/ms-marco-MiniLM-L-6-v2) kept — HF Hub repo names, still valid. Closes rohitg00#1095. Fixes rohitg00#479. Verified: 1424/1424 tests pass, build clean, tsc clean on migrated files.
8207bed to
826b8bf
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/providers/embedding/clip.ts`:
- Around line 59-65: Update loadTransformers() to catch errors, replace only
missing-module ERR_MODULE_NOT_FOUND failures with an embedding-agnostic
`@huggingface/transformers` installation hint, and rethrow all other errors
unchanged. Also update the provider.embed("hello") expectation in the CLIP
embedding provider test to avoid asserting the image-specific message.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: db31cfcc-2707-47cd-bda0-5af3b848b9fc
📒 Files selected for processing (25)
README.mdREADMEs/README.de-DE.mdREADMEs/README.es-ES.mdREADMEs/README.fr-FR.mdREADMEs/README.hi-IN.mdREADMEs/README.ja-JP.mdREADMEs/README.ko-KR.mdREADMEs/README.pt-BR.mdREADMEs/README.ru-RU.mdREADMEs/README.tr-TR.mdREADMEs/README.zh-CN.mdREADMEs/README.zh-TW.mdSECURITY.mdbenchmark/LONGMEMEVAL.mdbenchmark/REAL-EMBEDDINGS.mdbenchmark/real-embeddings-eval.tspackage.jsonsrc/providers/embedding/clip.tssrc/providers/embedding/local.tssrc/state/reranker.tssrc/xenova.d.tstest/clip-embedding-provider.test.tstest/local-embedding-provider.test.tstest/reranker.test.tstsdown.config.ts
💤 Files with no reviewable changes (1)
- src/xenova.d.ts
🚧 Files skipped from review as they are similar to previous changes (18)
- benchmark/REAL-EMBEDDINGS.md
- READMEs/README.tr-TR.md
- READMEs/README.ru-RU.md
- SECURITY.md
- src/state/reranker.ts
- tsdown.config.ts
- READMEs/README.zh-CN.md
- test/reranker.test.ts
- benchmark/LONGMEMEVAL.md
- READMEs/README.ko-KR.md
- READMEs/README.zh-TW.md
- READMEs/README.es-ES.md
- READMEs/README.hi-IN.md
- READMEs/README.pt-BR.md
- READMEs/README.de-DE.md
- README.md
- src/providers/embedding/local.ts
- READMEs/README.fr-FR.md
There was a problem hiding this comment.
Thanks @aqeelat for the PR
This is the right migration and it's carefully done. @xenova/transformers is the deprecated name for the same project, @huggingface/transformers is the maintained successor (xenova plus the HF team, same repo, Apache-2.0), and Node 22 support is exactly what #479 needs. The license table and keeping the Xenova/* model IDs are both correct.
Two things before it goes in:
-
The migrated tests mock
@huggingface/transformers, so the green suite proves the import swap is consistent but not that v4 actually runs. Since this swaps the embedding/rerank/clip backend, could you add one non-mocked smoke that loadsXenova/all-MiniLM-L6-v2, embeds a string, and asserts 384 dims plus finite values? Guarding it behind an env flag (orit.skipby default) is fine so CI doesn't download the model on every run. That's the piece that would catch a v4 output-shape change, which the mocked tests can't. -
The description says it renames
src/xenova.d.tstosrc/huggingface.d.ts, but the file is stillsrc/xenova.d.tsmodified in place. Ambient module declarations match on the module name, not the filename, so the rename is safe. Please rename the file so the name isn't stale, or drop the "rename" line from the description.
P.S: Everything needs to be documented in mintlify docs too.
One note, no action needed: onnxruntime-web comes in transitively as 1.26.0-dev. The Node runtime path uses onnxruntime-node, so the web prerelease shouldn't matter, just flagging it.
On CI: the test matrix hasn't built here because first-time contributor PRs need a maintainer to approve the workflow run. We'll trigger it. Once it's green on ubuntu and macOS across Node 20 and 22, and the two items above land, this is good to merge.
…atrix Review follow-ups for rohitg00#1096: - env-guarded non-mocked smoke test (RUN_HF_SMOKE=1) loading real Xenova/all-MiniLM-L6-v2, asserts 384 finite dims; skipped by default - selective ERR_MODULE_NOT_FOUND handling in local/clip providers so real init errors propagate (checks err.code and err.cause.code to handle vitest mock-factory wrapping) - CLIP install hint made embedding-agnostic (loader serves text + image) - afterEach mock cleanup in doMock-based provider/reranker tests - CI Node matrix: [20, 22] -> [20, 22, 24, 26] across ubuntu/macos
…g-module tests The .cause branch in the ERR_MODULE_NOT_FOUND check existed only to accommodate vitest's mock-factory wrapping, not a real Node loader behavior. Replace it with a manual mock fixture (__mocks__/@huggingface/ transformers.ts) that throws a Node-shaped error at module top-level, bypassing vitest's factory wrapper so the import rejects with err.code set directly. Production code now checks only err.code === 'ERR_MODULE_NOT_FOUND', matching real Node behavior. Tests verify the same public contract without coupling production code to the test framework.
|
@rohitg00 Both blocking items are in the last two commits ( 1. Non-mocked smoke test — 2. 3. Mintlify docs — I can't locate them in this repo ( Also addressed the CodeRabbit items while in here: the blanket import-catch in CI matrix expanded to |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/workflows/ci.yml:
- Line 55: Update the CI test step that runs npm test to set RUN_HF_SMOKE=1,
enabling test/local-embedding-smoke.test.ts while preserving the existing test
command and exclusions.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 37c04c40-632b-45a2-8612-237de10f30b9
📒 Files selected for processing (8)
.github/workflows/ci.yml__mocks__/@huggingface/transformers.tssrc/providers/embedding/clip.tssrc/providers/embedding/local.tstest/clip-embedding-provider.test.tstest/local-embedding-provider.test.tstest/local-embedding-smoke.test.tstest/reranker.test.ts
🚧 Files skipped from review as they are similar to previous changes (4)
- test/local-embedding-provider.test.ts
- src/providers/embedding/local.ts
- test/reranker.test.ts
- test/clip-embedding-provider.test.ts
| # rework before Windows can be added back. Tracked as follow-up. | ||
| os: [ubuntu-latest, macos-latest] | ||
| node-version: [20, 22] | ||
| node-version: [20, 22, 24, 26] |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
jq -r '.scripts.test // "<missing test script>"' package.json
rg -n 'RUN_HF_SMOKE' package.json .github/workflows/ci.ymlRepository: rohitg00/agentmemory
Length of output: 204
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
echo 'package test script:'
jq -r '.scripts.test // "<missing test script>"' package.json
echo
echo 'Workflow snippets around test invocation and env variables:'
sed -n '1,120p' .github/workflows/ci.yml
echo
echo 'RUN_HF_SMOKE occurrences:'
rg -n 'RUN_HF_SMOKE|HF|smoke|local-embedding' package.json .github/workflows/ci.yml test -S || trueRepository: rohitg00/agentmemory
Length of output: 2787
Enable the local embedding smoke test in CI.
The CI test step runs npm test, package scripts.test is vitest run --exclude test/integration.test.ts, and only test/local-embedding-smoke.test.ts gates on RUN_HF_SMOKE=1. Add RUN_HF_SMOKE to this step if the real-model embedding load should be part of CI.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.github/workflows/ci.yml at line 55, Update the CI test step that runs npm
test to set RUN_HF_SMOKE=1, enabling test/local-embedding-smoke.test.ts while
preserving the existing test command and exclusions.
2 participants
Summary
@xenova/transformers@2.17.2is deprecated and silently broken on Node 22+ (see #479). This swaps to@huggingface/transformers@^4.2.0— the same project, renamed, with an actively maintained ONNX runtime backend and Node 22/24 support. Drop-in for our usage:pipeline,RawImage.fromBlob,tolist, andtext-classificationoutput shape are all unchanged.Closes #1095. Fixes #479.
Changes
package.json: replace@xenova/transformers+ directonnxruntime-{node,web}optional deps with a single@huggingface/transformers@^4.2.0. The onnxruntime packages are now bundled as HF v4's hard deps;sharp,@huggingface/jinja, and@huggingface/tokenizerscome along transitively.src/xenova.d.ts(deleted): removed entirely —@huggingface/transformers@4.2.0ships its own TypeScript declarations (incl.RawImage), so the ambient shim is no longer needed.src/providers/embedding/{local,clip}.ts,src/state/reranker.ts: swap import specifier + install error strings. Drop theas unknown as TransformersModulecast inclip.ts. Import errors are now only rewritten to the install hint whenerr.code === "ERR_MODULE_NOT_FOUND"; all other failures propagate unchanged instead of being masked by a blanket catch. The CLIP hint is now embedding-agnostic (the loader serves both text and image paths).tsdown.config.ts: updateneverBundlelist.__mocks__/@huggingface/transformers.ts(new): manual mock fixture that throws a Node-shapedERR_MODULE_NOT_FOUNDat module top-level. Vitest'svi.mockfactory throws get wrapped (original lands on.cause), so a factory can't simulate a direct missing-module rejection. The manual mock bypasses the factory wrapper and lets the test exercise the realerr.codepath — production code checkserr.codeonly, with no test-framework coupling.test/{reranker,clip-embedding-provider,local-embedding-provider}.test.ts: use the manual mock for the "package unavailable" case;afterEachrestores module state in thedoMock-based describe blocks so mocks can't leak between tests.test/local-embedding-smoke.test.ts(new): non-mocked smoke test that loads the realXenova/all-MiniLM-L6-v2, embeds a string, and asserts 384 finite dims. Guarded byRUN_HF_SMOKE=1; skipped by default so CI doesn't download the model. This is the piece that catches a v4 output-shape change the mocked tests can't..github/workflows/ci.yml: expand Node matrix[20, 22]→[20, 22, 24, 26]across ubuntu/macos to cover every active LTS line plus current, proving the @xenova/transformers v2.17.2 fails on Node.js 22+ with "blob:nodedata:" worker URL error — semantic embedding silently disabled #479 Node 22/24 fix.README.md, 11READMEs/translations,SECURITY.md, 2 benchmark docs, and the benchmark script.Model IDs (
Xenova/all-MiniLM-L6-v2,Xenova/clip-vit-base-patch32,Xenova/ms-marco-MiniLM-L-6-v2) deliberately kept — HF Hub repo names, still valid under v3/v4.Verification
npm install— cleannpm test— 1424 passing, 1 skipped (the new smoke test)RUN_HF_SMOKE=1 npx vitest run test/local-embedding-smoke.test.ts— real v4 model load, 384 finite dims (downloads ~80MB once)npm run build— cleantsc --noEmiterrors are baseline (cli.ts, slots.ts, api.ts) — none touch migrated filesengines.nodestays>=20.0.0— the migration fixes Node 22/24 support rather than requiring it, so the floor remains honest. Node 20 is still in maintenance LTS and tested in CI.Open question for maintainer
You asked for this to be reflected in the mintlify docs too, but I can't find them in this repo (
docs/has onlybenchmarks/recipes;website/is a Next.js app with no.mdx/mint.json). Which repo/branch holds the mintlify docs?License check
@huggingface/transformers4.2.0 (new)@xenova/transformers2.17.2 (removed)onnxruntime-node1.14.0 → 1.24.3onnxruntime-web1.14.0 → 1.26.0-devsharp0.34.5 (new transitive)@huggingface/jinja(new transitive)@huggingface/tokenizers(new transitive)All permissive, all compatible with this repo's Apache-2.0. No NOTICE files required.
Follow-ups (deliberately out of scope)
Relates
Summary by CodeRabbit
New Features
Xenova/all-MiniLM-L6-v2model, providing 384-dimensional vectors.Documentation
Tests