feat(embeddings): add optional transformers.js companion for local embeddings

[arabold]

Why

Community PR #390 proposed adding @huggingface/transformers so users can run fully offline, local embeddings with no API key. The problem: that dependency plus the ONNX runtime is ~370 MB. Making it a hard dependency would bloat install size and the Docker image for the large majority of users who use a hosted embedding provider (OpenAI, Gemini, etc.).

This PR delivers the same offline-embeddings capability while keeping the heavy dependency optional.

Approach

The heavy dependency is externalized into a thin npm-workspace companion package, @arabold/docs-mcp-server-transformers, that simply re-exports pipeline/env from @huggingface/transformers. Integration code stays in the main repo and loads the companion lazily via a literal-string dynamic import, so:

• Users who want local embeddings run npm i -g @arabold/docs-mcp-server-transformers and select the transformers provider.
• Everyone else never downloads transformers or ONNX. The main bundle never imports it, even at the type level (the loader uses minimal structural types).

Key pieces:

• packages/transformers/ - companion re-exporter package, versioned in lockstep with the main package.
• transformersLoader.ts - cached lazy import plus precise missing-companion error mapping (only treats the bare package specifier as "not installed", so a broken internal path isn't misreported).
• TransformersJSEmbeddings.ts - LangChain Embeddings implementation on top of the loader.
• Provider plumbing - transformers added to the provider union and factory; areCredentialsAvailable returns true (no API key needed). Reuses main's generic dimension-resolution (from the recent Fix embedding dimension resolution for custom models #431 embedding-dimension rework) with no DocumentStore changes.
• Also corrects the known BAAI/bge-small-en-v1.5 dimension from 512 to 384.

Distribution

• Release (.releaserc.json, release.yml): the companion publishes in lockstep with the main package via a second @semantic-release/npm instance.
• Docker: companion is bundled into the image so the container works offline out of the box, with TRANSFORMERS_CACHE=/models exposed as a volume.
• CI (ci.yml, eval.yml): no changes needed - npm ci resolves the workspace and npm run build compiles the companion first (verified with a clean install).

Trade-offs worth a careful look

• For a known model, a missing companion surfaces at first embed rather than at init (the generic resolver only probes dimensions for unknown models). This is documented in the design.
• The root depends on the companion as a wildcard ("*") devDependency so lockstep version bumps never break workspace linking.

Notes

• Includes an OpenSpec change (add-transformers-companion) capturing the rationale, design, and spec deltas retroactively.
• Tests cover the loader error mapping, the embeddings class, and the new provider/dimension config paths.

[Copilot]

Pull request overview

Adds an optional Transformers.js companion workspace package to enable fully local/offline embeddings (no API key) without bloating the default install and bundle size for hosted-embeddings users. The main server integrates the new transformers: provider via a cached, literal-string dynamic import so the heavy @huggingface/transformers + ONNX runtime is only required when actually used.

Changes:

• Introduces @arabold/docs-mcp-server-transformers as an npm-workspace companion that re-exports Transformers.js (pipeline/env), and wires the repo to build/publish it in lockstep.
• Adds lazy loader + LangChain Embeddings implementation for transformers: models, and plumbs the provider through config/factory (including fixing BAAI/bge-small-en-v1.5 to 384 dims).
• Updates bundling (Vite external), Docker image packaging, release workflow, and docs/OpenSpec artifacts.

Reviewed changes

Copilot reviewed 25 out of 26 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
vite.config.ts	Externalizes the optional companion package so dynamic import is preserved and never bundled.
src/store/embeddings/transformersLoader.ts	Adds cached lazy import + missing-companion error classification.
src/store/embeddings/transformersLoader.test.ts	Tests loader error mapping and missing-companion error shape.
src/store/embeddings/TransformersJSEmbeddings.ts	Implements local/offline embeddings on top of Transformers.js with cache/device env support.
src/store/embeddings/TransformersJSEmbeddings.test.ts	Unit tests for query/batch embedding behavior, caching, env controls.
src/store/embeddings/EmbeddingFactory.ts	Adds transformers provider creation + credential availability rules.
src/store/embeddings/EmbeddingFactory.test.ts	Adds coverage ensuring transformers provider doesn’t require credentials.
src/store/embeddings/EmbeddingConfig.ts	Extends provider union + corrects known dimension for bge-small-en-v1.5.
src/store/embeddings/EmbeddingConfig.test.ts	Adds parsing test for transformers provider and corrected dimension.
docs/guides/embedding-models.md	Documents companion install + transformers: usage, cache/device env vars.
README.md	Updates top-level docs pointers to mention offline/local embeddings.
packages/transformers/package.json	Defines the companion package (name/version/exports/deps/scripts).
packages/transformers/src/index.ts	Thin re-exporter for Transformers.js (pipeline, env, pipeline type).
packages/transformers/tsconfig.json	TypeScript build config for the companion package output.
packages/transformers/README.md	Companion usage/install documentation.
package.json	Enables workspaces, builds companion before main build, adds wildcard devDep.
package-lock.json	Workspace linking + adds Transformers.js/ONNX dependency graph for dev/CI/Docker.
Dockerfile	Copies workspace metadata for npm ci, and ships companion in runtime image with /models cache volume.
.releaserc.json	Publishes companion package via a second semantic-release npm step and commits its package.json.
.github/workflows/release.yml	Adds manual publishing for the companion and commits its version bump.
openspec/changes/add-transformers-companion/*	Adds OpenSpec proposal/design/spec/tasks documenting the change retroactively.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[arabold]

Good catch - fixed in 69ea534. Both types and exports["."].types now point to the emitted ./dist/index.d.ts (the package emits declarations via tsc, and prepack builds dist/ before publish).

[arabold]

Correction: I reverted this in b4244d6 and kept types on ./src/index.ts. The main package type-checks the companion through the dynamic import() in transformersLoader.ts, and the lint/typecheck CI job does not build the companion, so pointing types at ./dist/index.d.ts breaks tsc with TS2307 (the declaration file does not exist yet). The companion publishes both src and dist, so consumers still get types from source. This keeps the main repo type-check independent of the companion build, which is the intended setup.

[arabold]

This one predates this PR - on main, createEmbeddingModel() already has no case "sagemaker" even though the union and UnsupportedProviderError message list it (areCredentialsAvailable() does handle it, which is the inconsistency). This PR only adds the transformers provider and does not touch the sagemaker path, so I have left it out of scope to keep the change focused. Happy to file a follow-up to either implement the SageMaker case or drop it from the supported list.