RAG Pipeline Utils v3.0: Node 22, a Smaller Install and a Cleaner Main Entry

v3.0.0 is a clean-up release. It removes what 2.x deprecated, requires Node.js 22 and makes the OpenAI SDK an install you choose. The pipeline API, plugin contracts, .ragrc.json files and CLI commands don't change, so most projects upgrade by checking their Node version and, if they use OpenAI, running one extra install.

npm install @devilsdev/rag-pipeline-utils@^3.0.0

The step-by-step checklist is in the migration guide: Upgrading to v3.0.0. This post explains what changed and why.

Node.js 22 or later

Node 18 and 20 have reached end of life, so 3.0.0 requires Node 22 (engines.node >= 22). CI now tests Node 22 and 24. If you can't move off Node 18 or 20 yet, stay on 2.7.x, which keeps receiving security fixes for 30 days after this release.

Getting Node 24 into CI found two problems worth knowing about if you build native modules:

• isolated-vm 5 doesn't build on Node 24, whose V8 headers need C++20. The experimental PluginSandbox now needs isolated-vm 6, which supports Node 22 and later.
• npm 11, which ships with Node 24, refuses a lockfile that lacks other platforms' optional packages. The lockfile now records every platform's esbuild and sharp binaries.

The OpenAI SDK: version 7, and only if you use it

The openai SDK moves from 4.x to 7.x, and it is no longer installed for everyone. It is now an optional peer dependency, so a project that uses OpenAI installs it alongside the package:

npm install @devilsdev/rag-pipeline-utils openai

Any version from 4.93 works. OpenAIConnector was run against 4.104, 5.23, 6.49 and 7.45 on the same set of checks (generation, streaming, embeddings, rate-limit retries, client errors, cancellation and connection failures) and behaves the same on all four, so a project that already pins its own openai keeps it. Without the SDK, the connector's methods fail with code MISSING_DEPENDENCY and the install command, and rag-pipeline init with the openai template prints it too. The Anthropic, Cohere, Ollama and local connectors need nothing extra.

The install is smaller as a result:

Clean npm install	Size	Packages
2.7.1	58 MB	188
3.0.0	47 MB	172

Bundling openai 7 for everyone would have meant 77 MB.

Connection failures are retried again

openai 5 and later use Node's built-in fetch, which reports a refused connection one level deeper than before: the socket error now sits inside a TypeError('fetch failed'). The connectors' retry check only looked one level down, so with the new SDK a refused connection would have failed on the first attempt. Testing for that also found an older bug: the SDK's connection error classes keep name: "Error", so the check for APIConnectionTimeoutError never matched, and timeouts were never retried, on 4.x either. The retry check now matches the error class and walks the cause chain. As a result, a request to an unresponsive OpenAI endpoint is now retried up to maxRetries (default 3) before failing; lower it if you'd rather fail fast.

Experimental classes leave the main entry

Since 2.5.0, the simulated or incomplete classes (model training, federated learning, multimodal processing, adaptive retrieval, the SSO providers, multi-tenancy (TenantManager, ResourceMonitor), data governance, PluginSandbox and PluginCertification) have lived in their own entry point and warned when constructed or called through the main one. In 3.0.0 the main entry no longer exports them:

- import { TenantManager } from "@devilsdev/rag-pipeline-utils";
+ import { TenantManager } from "@devilsdev/rag-pipeline-utils/experimental";

To find the imports to change, search your code for the class names. Running your app or tests on 2.7.x with node --trace-deprecation helps too: each RAG_DEP_* warning shows the first place your code constructs that class, once per class per run, but an import that is never constructed (or only used for instanceof) doesn't warn. Both entries share the same classes in 2.x, so you can change the imports before upgrading. Importing the package also no longer loads these modules at all.

Types that described the wrong thing are gone

2.7.0 rebuilt the TypeScript declarations from the source and deprecated six types and one field that didn't match what the code reads or returns: LoadConfigOptions, LLMResponse, DAGNode, DAGOptions, ErrorFormatter, EvalResult and Document.embedding. 3.0.0 removes them. The migration guide lists a replacement for each, and every replacement there was compiled with --strict against the 3.0 declarations.

What's next

The roadmap for 3.x includes splitting the package into scoped packages, an OpenTelemetry exporter, packing context to a token budget, a plugin contract test kit, and making HTML loading and the CLI's interactive prompts optional installs too.

The full list of changes is in the CHANGELOG.