From 472b4bac1358d3abcdb10efdd62db5c1e3a9b07d Mon Sep 17 00:00:00 2001 From: opaninakuffo Date: Mon, 24 Aug 2026 10:39:44 +0000 Subject: [PATCH 1/3] chore[notask]: release @qvac/rag v0.7.0 --- packages/rag/CHANGELOG.md | 183 +++++++++++++++--- packages/rag/NOTICE | 1 + packages/rag/changelog/0.6.4/CHANGELOG.md | 7 + packages/rag/changelog/0.6.4/CHANGELOG_LLM.md | 11 ++ packages/rag/changelog/0.7.0/CHANGELOG.md | 22 +++ packages/rag/changelog/0.7.0/CHANGELOG_LLM.md | 31 +++ packages/rag/changelog/0.7.0/api.md | 15 ++ packages/rag/changelog/0.7.0/breaking.md | 19 ++ packages/rag/package.json | 2 +- 9 files changed, 259 insertions(+), 32 deletions(-) create mode 100644 packages/rag/changelog/0.6.4/CHANGELOG.md create mode 100644 packages/rag/changelog/0.6.4/CHANGELOG_LLM.md create mode 100644 packages/rag/changelog/0.7.0/CHANGELOG.md create mode 100644 packages/rag/changelog/0.7.0/CHANGELOG_LLM.md create mode 100644 packages/rag/changelog/0.7.0/api.md create mode 100644 packages/rag/changelog/0.7.0/breaking.md diff --git a/packages/rag/CHANGELOG.md b/packages/rag/CHANGELOG.md index ef1a20bf1d..337a39ca91 100644 --- a/packages/rag/CHANGELOG.md +++ b/packages/rag/CHANGELOG.md @@ -1,71 +1,192 @@ # Changelog -All notable changes to this project will be documented in this file. +## [0.7.0] -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +๐Ÿ“ฆ **NPM:** https://www.npmjs.com/package/@qvac/rag/v/0.7.0 + +`@qvac/rag` is now TypeScript compiled to ESM. CommonJS `require('@qvac/rag')` no longer works โ€” switch to `import`. Invalid `search` and `infer` queries throw `QvacErrorRAG` with `INVALID_INPUT` instead of a raw `TypeError`. Named exports are unchanged. + +## Breaking Changes + +### ESM only + +The package is `"type": "module"`. Node rejects `require()` of ESM. Use `import`. Named exports (`RAG`, `HyperDBAdapter`, adapters, `ERR_CODES`, `QvacErrorRAG`) are the same. `@qvac/rag/errors` still exports the error class and codes without loading the full package. + +**Before:** + +```js +const { RAG, HyperDBAdapter } = require('@qvac/rag') +``` + +**After:** + +```ts +import { RAG, HyperDBAdapter } from '@qvac/rag' +``` + +The 0.6.1 Pear/CJS `require()` path for hard dependencies is gone with this conversion. Pear consumers need an ESM-capable loader. + +## Bug Fixes + +### Query validated before logging + +`rag.search()` and `rag.infer()` reject a non-string or blank query with `QvacErrorRAG { code: INVALID_INPUT }` before any debug log reads `query.substring`. Valid queries are unchanged. Previously a non-string hit `TypeError` at the log line and never reached the existing search guard. ## [0.6.4] -### Changed +๐Ÿ“ฆ **NPM:** https://www.npmjs.com/package/@qvac/rag/v/0.6.4 + +This patch drops the unused `crypto-browserify` hard dependency. The package never imported it. + +## Changed + +### Unused `crypto-browserify` dependency removed -- Drop the unused `crypto-browserify` hard dependency. The package never imported it โ€” `#crypto` resolves to `bare-crypto` (Bare) or `node:crypto` (Node), and the browser / React Native shim reads `globalThis.crypto`. Consumers needing Node-style `crypto.createHash` (e.g. HyperDB document hashing in a browser/RN runtime) should install `crypto-browserify` themselves and assign it to `globalThis.crypto`, as documented in the README. +`#crypto` still resolves to `bare-crypto` on Bare, `node:crypto` on Node, and `globalThis.crypto` on browser / React Native. Consumers that need Node-style `crypto.createHash` (for example HyperDB document hashing in a browser or React Native runtime) should install `crypto-browserify` themselves and assign it to `globalThis.crypto`, as documented in the README. ## [0.6.3] -### Changed +๐Ÿ“ฆ **NPM:** https://www.npmjs.com/package/@qvac/rag/v/0.6.3 -- Bump `bare-fetch` to `^3.0.1` (adopt the 3.x major; public fetch API unchanged). +This patch bumps the production `bare-fetch` dependency across the 2โ†’3 major to `^3.0.1`. + +--- + +## ๐Ÿ”ง Changed + +### `bare-fetch` bumped to `^3.0.1` + +The 2โ†’3 transition is transitive-only โ€” the public fetch API is unchanged. The only behavioral change in 3.x is the header validation added in 3.0.1, and RAG only constructs RFC-valid headers, so no code change is required. The bare-tls trust-store change already shipped within the 2.x line via `bun.lock`. ## [0.6.2] -### Fixed +๐Ÿ“ฆ **NPM:** https://www.npmjs.com/package/@qvac/rag/v/0.6.2 + +This patch fixes a package exports gap that broke SDK consumer installs when TypeScript compiled `@qvac/rag/errors` imports to `@qvac/rag/errors.js`. + +--- + +## ๐Ÿ”Œ API -- Add `./errors.js` export alias so TypeScript ESM emit (`@qvac/rag/errors.js`) resolves under Node package exports. +### `./errors.js` export alias + +TypeScript ESM output appends `.js` to subpath imports. Node enforces `package.json#exports` strictly, so `@qvac/rag/errors.js` failed even though `@qvac/rag/errors` worked. This release adds a matching `./errors.js` export entry pointing at the same module as `./errors`. + +No API surface change โ€” existing `@qvac/rag/errors` imports continue to work unchanged. ## [0.6.1] -### Added +๐Ÿ“ฆ **NPM:** https://www.npmjs.com/package/@qvac/rag/v/0.6.1 + +This patch restores Pear/CJS compatibility for RAG adapters and adds a lightweight `./errors` subpath so SDK consumers can import error codes without pulling in the full package entry. + +--- + +## ๐Ÿž Fixes + +### Pear/CJS compatibility (#2284) + +RAG adapters now load hard dependencies (`hyperdb`, `hyperschema`, `llm-splitter`, `#fetch`) via synchronous `require()` instead of dynamic `await import()`. This fixes `MODULE_NOT_FOUND` failures when running RAG under Pear, where ESM dynamic imports are unavailable in the CJS module graph. -- Published `@qvac/rag/errors` subpath for importing `ERR_CODES` and `QvacErrorRAG` without loading the full package entry (#2303). +--- -### Fixed +## ๐Ÿ”Œ API -- Load RAG hard dependencies (`hyperdb`, `hyperschema`, `llm-splitter`, `#fetch`) via synchronous `require()` instead of dynamic `await import()` for Pear/CJS compatibility (#2284). +### `@qvac/rag/errors` subpath (#2303) + +Consumers can now import RAG error codes and the error class from a dedicated subpath that does not transitively load `HyperDBAdapter` or other heavy runtime deps: + +```typescript +import { ERR_CODES, QvacErrorRAG } from '@qvac/rag/errors' + +if (err instanceof QvacErrorRAG && err.code === ERR_CODES.OPERATION_CANCELLED) { + // handle cancellation +} +``` + +Existing `import { ERR_CODES } from "@qvac/rag"` continues to work unchanged. ## [0.6.0] -### Changed +๐Ÿ“ฆ **NPM:** https://www.npmjs.com/package/@qvac/rag/v/0.6.0 + +This release completes the HyperDB 6 migration for `@qvac/rag`, aligning with the published `@qvac/registry-schema@0.3.0` and `@qvac/registry-client@0.6.0` stack. RAG now owns the Holepunch libraries it imports at runtime as direct dependencies instead of optional peers. The public RAG API is unchanged. + +--- + +## ๐Ÿ”ง Changed + +### HyperDB 6 and regenerated specs (#2255) -- Upgrade to HyperDB 6 (`hyperdb@^6.7.0`), regenerate RAG HyperDB specs for the v6 toolchain, and move runtime Holepunch libraries from `peerDependencies` to direct `dependencies` (#2255). -- Bump `@qvac/registry-client` dev dependency to `^0.6.0`. +`hyperdb` is bumped from the HyperDB 4 peer range to `^6.7.0` as a direct dependency. The autogenerated HyperDB spec under `src/adapters/database/hyperspec/` is rebuilt with the HyperDB 6 compiler output. + +### Dependency graph cleanup + +Runtime imports (`bare-crypto`, `bare-fetch`, `hyperdb`, `hyperdht`, `hyperschema`, `llm-splitter`) move from `peerDependencies` back to direct `dependencies` โ€” matching the registry hyperdb v6 cascade and avoiding peer-range drift when installed alongside `@qvac/sdk`. The `@qvac/registry-client` dev dependency is bumped to `^0.6.0` for examples and integration tests. ## [0.5.0] -### Fixed +๐Ÿ“ฆ **NPM:** https://www.npmjs.com/package/@qvac/rag/v/0.5.0 + +This release makes `@qvac/rag` a first-class citizen in non-Bare runtimes โ€” React Native and Expo bundlers no longer choke on Bare-specific imports โ€” and tightens the package's place in the SDK install graph so Holepunch singletons (DHT, Corestore, HyperDB) are no longer duplicated in consumer trees. It also lands a small but real bug fix in RAG's crypto-fallback error path so consumers can finally catch missing-dependency errors by code. + +--- + +## ๐Ÿž Fixes + +### React Native / Expo bundling: `LLMChunkAdapter` is exported again + +Previously, importing `@qvac/rag` from a React Native or Expo project failed with `SyntaxError: 'LLMChunkAdapter' not exported` even though the export was present in the source โ€” the bundler was getting corrupted output because RAG's source had hard `bare-crypto` and `bare-fetch` imports that non-Bare bundlers tried (and failed) to resolve. -- React Native / Expo bundling: routed `bare-crypto` and `bare-fetch` through `package.json#imports` (`#crypto`, `#fetch`) with lazy shims, so non-Bare bundlers no longer corrupt the package output (e.g. `SyntaxError: 'LLMChunkAdapter' not exported`). Missing capabilities now throw `QvacErrorRAG { DEPENDENCY_REQUIRED }` only when invoked. -- `generateId()` no longer mutates a global `crypto` or depends on `uuid-random`; UUID v4s are generated locally using secure randomness from `globalThis.crypto.getRandomValues` or `#crypto.randomBytes` / `getRandomValues`. -- `QvacErrorRAG` construction in RAG crypto fallbacks now uses the canonical `{ code, adds }` options object so the documented `DEPENDENCY_REQUIRED` (14015) error code is actually thrown (previously degraded to code `0` / `"Unknown QVAC error"`). +Bare-specific dependencies are now routed through Node.js `package.json#imports` so the right module is selected per runtime: -### Changed +- `#crypto` resolves to `bare-crypto` on Bare, `node:crypto` on Node, and a lazy shim on React Native and other targets. +- `#fetch` resolves to `bare-fetch` on Bare and a lazy shim on Node, React Native, and other targets. -- Holepunch singletons (`hyperdb`, `hyperdht`, `hyperschema`, `bare-crypto`, `bare-fetch`, `llm-splitter`) moved from `dependencies` to `peerDependencies` so consumer trees install a single copy aligned with `@qvac/sdk`'s ranges. `hyperdht` is marked optional (reserved for the unwired `replicateWith` path). -- Examples and integration tests migrated off `@qvac/dl-hyperdrive` to `@qvac/registry-client` (files-based addon construction). `devDependencies` updated accordingly: removed `@qvac/dl-hyperdrive`, added `@qvac/registry-client@^0.4.1`, bumped `@qvac/embed-llamacpp` `^0.7.6 โ†’ ^0.14.0` and `@qvac/llm-llamacpp` `^0.5.7 โ†’ ^0.16.0`. +The shims allow bundling to succeed and only throw `QvacErrorRAG { DEPENDENCY_REQUIRED }` if the missing capability is actually invoked at runtime. Consumers on browsers, React Native, or Node who need Node-style `crypto.createHash` (notably for HyperDB document hashing) can install `crypto-browserify`, which is now declared as an **optional peer dependency**. -### Added +`generateId()` no longer mutates a global `crypto` or depends on `uuid-random`. It generates UUID v4 IDs locally using secure randomness from `globalThis.crypto.getRandomValues` or `#crypto.randomBytes` / `getRandomValues`, and throws a clear error if neither is available. -- `crypto-browserify` as an optional peer dependency for browser / React Native consumers that need Node-style `crypto.createHash` (notably for HyperDB document hashing). +### `QvacErrorRAG` in crypto fallbacks now reports the correct error code + +Two RAG crypto-fallback call sites were constructing `QvacErrorRAG` with positional arguments `(code, message)` instead of the canonical `{ code, adds }` options object. Because `QvacErrorBase` destructures its single options argument, the thrown error silently degraded to code `0` / `"Unknown QVAC error"` instead of the intended `DEPENDENCY_REQUIRED` (14015) โ€” so consumers catching by code never matched. Both call sites in `helper.js` and `HyperDBAdapter.js` now use the canonical form, and the documented error code is what's actually thrown. + +--- + +## ๐Ÿงน Maintenance + +### Holepunch singletons moved to `peerDependencies` + +`@qvac/rag` previously declared `hyperdb`, `hyperdht`, `hyperschema`, `bare-crypto`, `bare-fetch`, and `llm-splitter` as hard dependencies. When the SDK declared its own (drifting) ranges for these as peers, npm could end up installing duplicate copies of stateful singletons in a consumer's tree โ€” separate DHT nodes, separate Corestores, broken P2P connectivity. These libraries are now `peerDependencies` (mirrored in `devDependencies` so the package still builds and tests in isolation), and `@qvac/sdk` is the single source of truth for the actual installed range. `hyperdht` is marked optional in RAG since it is reserved for the not-yet-wired `replicateWith` path. + +Consumers using `@qvac/sdk` or any tooling that auto-installs required peers (npm 7+, pnpm, bun) are unaffected โ€” the peers resolve transparently. Direct standalone consumers of `@qvac/rag` using `yarn` or `legacy-peer-deps=true` may now see missing-peer warnings and should add `hyperdb`, `hyperschema`, and `bare-crypto` (and `bare-fetch` if used in a Bare runtime) to their own dependencies. + +### DataLoader cleanup: examples and integration tests off `@qvac/dl-hyperdrive` + +The RAG examples and integration test no longer depend on `@qvac/dl-hyperdrive`. Model fetching now goes through `@qvac/registry-client` (mirroring how the SDK and OCR addons consume the QVAC registry), and the addon construction has migrated from the old `HyperDriveDL` + loader-based shape to the current files-based shape (`{ files, config, logger, opts }`). + +To support this, `devDependencies` were updated: + +- Removed: `@qvac/dl-hyperdrive` +- Added: `@qvac/registry-client@^0.4.1` +- Bumped: `@qvac/embed-llamacpp` `^0.7.6 โ†’ ^0.14.0`, `@qvac/llm-llamacpp` `^0.5.7 โ†’ ^0.16.0` (versions that ship the files-based API). + +This is purely a developer-facing change โ€” runtime behavior of `@qvac/rag` is unchanged. The SDK-side `overrides: { @qvac/dl-hyperdrive: ^0.2.0 }` is intentionally retained until the addons-side cleanup of `@qvac/infer-base`'s `dl-hyperdrive` peer dep lands. ## [0.4.4] -### Changed +๐Ÿ“ฆ **NPM:** https://www.npmjs.com/package/@qvac/rag/v/0.4.4 + +This release focuses on dependency hygiene and package namespace consistency for the RAG library. It aligns documentation with the `@qvac` npm scope and updates core crypto dependency declarations to match current runtime expectations. + +--- + +## ๐Ÿ“˜ Documentation -- README: replaced `@tetherto` npm references with `@qvac` namespace references. -- Dependencies: bumped `bare-crypto` to `^1.13.4` and cleaned up RAG package dependency declarations. +README references have been updated from the legacy `@tetherto` namespace to `@qvac`, reducing installation confusion and ensuring examples match currently published package names. -## [0.4.3] +--- -### Changed +## ๐Ÿงน Maintenance -- README: removed outdated npm Personal Access Token / `.npmrc` setup instructions for installing `@qvac/rag`. +`bare-crypto` dependency declarations were updated to `^1.13.4`, and related `package.json` cleanup was applied in the RAG package. This keeps dependency metadata aligned with the current SDK pod ecosystem and reduces drift across package manifests. diff --git a/packages/rag/NOTICE b/packages/rag/NOTICE index b9be65e705..c781e48915 100644 --- a/packages/rag/NOTICE +++ b/packages/rag/NOTICE @@ -15,6 +15,7 @@ JavaScript Dependencies @hyperswarm/secret-stream@6.9.1 https://github.com/holepunchto/hyperswarm-secret-stream @qvac/error@0.1.1 + @qvac/logging@0.1.1 adaptive-timeout@1.0.1 https://github.com/holepunchto/adaptive-timeout b4a@1.8.1 diff --git a/packages/rag/changelog/0.6.4/CHANGELOG.md b/packages/rag/changelog/0.6.4/CHANGELOG.md new file mode 100644 index 0000000000..92d6bde451 --- /dev/null +++ b/packages/rag/changelog/0.6.4/CHANGELOG.md @@ -0,0 +1,7 @@ +# Changelog v0.6.4 + +Release Date: 2026-06-15 + +## ๐Ÿ”ง Changed + +- Drop the unused `crypto-browserify` hard dependency. The package never imported it โ€” `#crypto` resolves to `bare-crypto` (Bare) or `node:crypto` (Node), and the browser / React Native shim reads `globalThis.crypto`. Consumers needing Node-style `crypto.createHash` (e.g. HyperDB document hashing in a browser/RN runtime) should install `crypto-browserify` themselves and assign it to `globalThis.crypto`, as documented in the README. diff --git a/packages/rag/changelog/0.6.4/CHANGELOG_LLM.md b/packages/rag/changelog/0.6.4/CHANGELOG_LLM.md new file mode 100644 index 0000000000..7753d6913e --- /dev/null +++ b/packages/rag/changelog/0.6.4/CHANGELOG_LLM.md @@ -0,0 +1,11 @@ +# QVAC RAG v0.6.4 Release Notes + +๐Ÿ“ฆ **NPM:** https://www.npmjs.com/package/@qvac/rag/v/0.6.4 + +This patch drops the unused `crypto-browserify` hard dependency. The package never imported it. + +## Changed + +### Unused `crypto-browserify` dependency removed + +`#crypto` still resolves to `bare-crypto` on Bare, `node:crypto` on Node, and `globalThis.crypto` on browser / React Native. Consumers that need Node-style `crypto.createHash` (for example HyperDB document hashing in a browser or React Native runtime) should install `crypto-browserify` themselves and assign it to `globalThis.crypto`, as documented in the README. diff --git a/packages/rag/changelog/0.7.0/CHANGELOG.md b/packages/rag/changelog/0.7.0/CHANGELOG.md new file mode 100644 index 0000000000..7ddf6c8d52 --- /dev/null +++ b/packages/rag/changelog/0.7.0/CHANGELOG.md @@ -0,0 +1,22 @@ +# Changelog v0.7.0 + +Release Date: 2026-08-24 + +## ๐Ÿ”Œ API + +- Expose @qvac/rag/errors subpath for consumers. (see PR [#2303](https://github.com/tetherto/qvac/pull/2303)) - See [API changes](./api.md) + +## ๐Ÿž Fixes + +- Load RAG hard deps with require() for Pear/CJS compatibility. (see PR [#2284](https://github.com/tetherto/qvac/pull/2284)) +- Validate RAG query before logging it. (see PR [#3729](https://github.com/tetherto/qvac/pull/3729)) + +## ๐Ÿ“˜ Docs + +- Update npm package homepage metadata. (see PR [#2810](https://github.com/tetherto/qvac/pull/2810)) + +## ๐Ÿงน Chores + +- Switch @qvac/rag to Lunte and Prettier. (see PR [#2801](https://github.com/tetherto/qvac/pull/2801)) +- Unify lint/format/typecheck across SDK-pod packages. (see PR [#3040](https://github.com/tetherto/qvac/pull/3040)) +- Convert @qvac/rag to TypeScript ESM. (see PR [#3718](https://github.com/tetherto/qvac/pull/3718)) - See [breaking changes](./breaking.md) diff --git a/packages/rag/changelog/0.7.0/CHANGELOG_LLM.md b/packages/rag/changelog/0.7.0/CHANGELOG_LLM.md new file mode 100644 index 0000000000..dda1943a68 --- /dev/null +++ b/packages/rag/changelog/0.7.0/CHANGELOG_LLM.md @@ -0,0 +1,31 @@ +# QVAC RAG v0.7.0 Release Notes + +๐Ÿ“ฆ **NPM:** https://www.npmjs.com/package/@qvac/rag/v/0.7.0 + +`@qvac/rag` is now TypeScript compiled to ESM. CommonJS `require('@qvac/rag')` no longer works โ€” switch to `import`. Invalid `search` and `infer` queries throw `QvacErrorRAG` with `INVALID_INPUT` instead of a raw `TypeError`. Named exports are unchanged. + +## Breaking Changes + +### ESM only + +The package is `"type": "module"`. Node rejects `require()` of ESM. Use `import`. Named exports (`RAG`, `HyperDBAdapter`, adapters, `ERR_CODES`, `QvacErrorRAG`) are the same. `@qvac/rag/errors` still exports the error class and codes without loading the full package. + +**Before:** + +```js +const { RAG, HyperDBAdapter } = require('@qvac/rag') +``` + +**After:** + +```ts +import { RAG, HyperDBAdapter } from '@qvac/rag' +``` + +The 0.6.1 Pear/CJS `require()` path for hard dependencies is gone with this conversion. Pear consumers need an ESM-capable loader. + +## Bug Fixes + +### Query validated before logging + +`rag.search()` and `rag.infer()` reject a non-string or blank query with `QvacErrorRAG { code: INVALID_INPUT }` before any debug log reads `query.substring`. Valid queries are unchanged. Previously a non-string hit `TypeError` at the log line and never reached the existing search guard. diff --git a/packages/rag/changelog/0.7.0/api.md b/packages/rag/changelog/0.7.0/api.md new file mode 100644 index 0000000000..facc5ee48c --- /dev/null +++ b/packages/rag/changelog/0.7.0/api.md @@ -0,0 +1,15 @@ +# ๐Ÿ”Œ API Changes v0.7.0 + +## Expose @qvac/rag/errors subpath for consumers + +PR: [#2303](https://github.com/tetherto/qvac/pull/2303) + +```typescript +import { ERR_CODES, QvacErrorRAG } from '@qvac/rag/errors' + +if (err instanceof QvacErrorRAG && err.code === ERR_CODES.OPERATION_CANCELLED) { + // handle cancellation +} +``` + +--- diff --git a/packages/rag/changelog/0.7.0/breaking.md b/packages/rag/changelog/0.7.0/breaking.md new file mode 100644 index 0000000000..48156c3b2a --- /dev/null +++ b/packages/rag/changelog/0.7.0/breaking.md @@ -0,0 +1,19 @@ +# ๐Ÿ’ฅ Breaking Changes v0.7.0 + +## Convert @qvac/rag to TypeScript ESM + +PR: [#3718](https://github.com/tetherto/qvac/pull/3718) + +**BEFORE:** + +```js +const { RAG, HyperDBAdapter } = require('@qvac/rag') +``` + +**AFTER:** + +```ts +import { RAG, HyperDBAdapter } from '@qvac/rag' +``` + +--- diff --git a/packages/rag/package.json b/packages/rag/package.json index 1636bcadfd..4752504df7 100644 --- a/packages/rag/package.json +++ b/packages/rag/package.json @@ -1,6 +1,6 @@ { "name": "@qvac/rag", - "version": "0.6.4", + "version": "0.7.0", "type": "module", "main": "./dist/index.js", "types": "./dist/index.d.ts", From 80352354456642da161bc9436a5c6fbdf283c085 Mon Sep 17 00:00:00 2001 From: opaninakuffo Date: Mon, 24 Aug 2026 11:31:04 +0000 Subject: [PATCH 2/3] chore[notask]: restore Keep a Changelog format for @qvac/rag root CHANGELOG Leave 0.6.4 and below unchanged; prepend a short 0.7.0 block only. --- packages/rag/CHANGELOG.md | 183 ++++++++------------------------------ 1 file changed, 36 insertions(+), 147 deletions(-) diff --git a/packages/rag/CHANGELOG.md b/packages/rag/CHANGELOG.md index 337a39ca91..e1178beb6d 100644 --- a/packages/rag/CHANGELOG.md +++ b/packages/rag/CHANGELOG.md @@ -1,192 +1,81 @@ # Changelog -## [0.7.0] - -๐Ÿ“ฆ **NPM:** https://www.npmjs.com/package/@qvac/rag/v/0.7.0 - -`@qvac/rag` is now TypeScript compiled to ESM. CommonJS `require('@qvac/rag')` no longer works โ€” switch to `import`. Invalid `search` and `infer` queries throw `QvacErrorRAG` with `INVALID_INPUT` instead of a raw `TypeError`. Named exports are unchanged. - -## Breaking Changes - -### ESM only - -The package is `"type": "module"`. Node rejects `require()` of ESM. Use `import`. Named exports (`RAG`, `HyperDBAdapter`, adapters, `ERR_CODES`, `QvacErrorRAG`) are the same. `@qvac/rag/errors` still exports the error class and codes without loading the full package. - -**Before:** +All notable changes to this project will be documented in this file. -```js -const { RAG, HyperDBAdapter } = require('@qvac/rag') -``` +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -**After:** - -```ts -import { RAG, HyperDBAdapter } from '@qvac/rag' -``` +## [0.7.0] -The 0.6.1 Pear/CJS `require()` path for hard dependencies is gone with this conversion. Pear consumers need an ESM-capable loader. +### Changed -## Bug Fixes +- Convert `@qvac/rag` to TypeScript compiled ESM (`"type": "module"`). CommonJS `require('@qvac/rag')` no longer works โ€” switch to `import`. Named exports are unchanged (#3718). -### Query validated before logging +### Fixed -`rag.search()` and `rag.infer()` reject a non-string or blank query with `QvacErrorRAG { code: INVALID_INPUT }` before any debug log reads `query.substring`. Valid queries are unchanged. Previously a non-string hit `TypeError` at the log line and never reached the existing search guard. +- Validate `search` and `infer` queries before logging so a non-string or blank query throws `QvacErrorRAG { code: INVALID_INPUT }` instead of a raw `TypeError` (#3729). ## [0.6.4] -๐Ÿ“ฆ **NPM:** https://www.npmjs.com/package/@qvac/rag/v/0.6.4 - -This patch drops the unused `crypto-browserify` hard dependency. The package never imported it. - -## Changed +### Changed -### Unused `crypto-browserify` dependency removed - -`#crypto` still resolves to `bare-crypto` on Bare, `node:crypto` on Node, and `globalThis.crypto` on browser / React Native. Consumers that need Node-style `crypto.createHash` (for example HyperDB document hashing in a browser or React Native runtime) should install `crypto-browserify` themselves and assign it to `globalThis.crypto`, as documented in the README. +- Drop the unused `crypto-browserify` hard dependency. The package never imported it โ€” `#crypto` resolves to `bare-crypto` (Bare) or `node:crypto` (Node), and the browser / React Native shim reads `globalThis.crypto`. Consumers needing Node-style `crypto.createHash` (e.g. HyperDB document hashing in a browser/RN runtime) should install `crypto-browserify` themselves and assign it to `globalThis.crypto`, as documented in the README. ## [0.6.3] -๐Ÿ“ฆ **NPM:** https://www.npmjs.com/package/@qvac/rag/v/0.6.3 - -This patch bumps the production `bare-fetch` dependency across the 2โ†’3 major to `^3.0.1`. - ---- +### Changed -## ๐Ÿ”ง Changed - -### `bare-fetch` bumped to `^3.0.1` - -The 2โ†’3 transition is transitive-only โ€” the public fetch API is unchanged. The only behavioral change in 3.x is the header validation added in 3.0.1, and RAG only constructs RFC-valid headers, so no code change is required. The bare-tls trust-store change already shipped within the 2.x line via `bun.lock`. +- Bump `bare-fetch` to `^3.0.1` (adopt the 3.x major; public fetch API unchanged). ## [0.6.2] -๐Ÿ“ฆ **NPM:** https://www.npmjs.com/package/@qvac/rag/v/0.6.2 - -This patch fixes a package exports gap that broke SDK consumer installs when TypeScript compiled `@qvac/rag/errors` imports to `@qvac/rag/errors.js`. - ---- - -## ๐Ÿ”Œ API - -### `./errors.js` export alias - -TypeScript ESM output appends `.js` to subpath imports. Node enforces `package.json#exports` strictly, so `@qvac/rag/errors.js` failed even though `@qvac/rag/errors` worked. This release adds a matching `./errors.js` export entry pointing at the same module as `./errors`. +### Fixed -No API surface change โ€” existing `@qvac/rag/errors` imports continue to work unchanged. +- Add `./errors.js` export alias so TypeScript ESM emit (`@qvac/rag/errors.js`) resolves under Node package exports. ## [0.6.1] -๐Ÿ“ฆ **NPM:** https://www.npmjs.com/package/@qvac/rag/v/0.6.1 - -This patch restores Pear/CJS compatibility for RAG adapters and adds a lightweight `./errors` subpath so SDK consumers can import error codes without pulling in the full package entry. - ---- - -## ๐Ÿž Fixes - -### Pear/CJS compatibility (#2284) - -RAG adapters now load hard dependencies (`hyperdb`, `hyperschema`, `llm-splitter`, `#fetch`) via synchronous `require()` instead of dynamic `await import()`. This fixes `MODULE_NOT_FOUND` failures when running RAG under Pear, where ESM dynamic imports are unavailable in the CJS module graph. - ---- - -## ๐Ÿ”Œ API +### Added -### `@qvac/rag/errors` subpath (#2303) +- Published `@qvac/rag/errors` subpath for importing `ERR_CODES` and `QvacErrorRAG` without loading the full package entry (#2303). -Consumers can now import RAG error codes and the error class from a dedicated subpath that does not transitively load `HyperDBAdapter` or other heavy runtime deps: +### Fixed -```typescript -import { ERR_CODES, QvacErrorRAG } from '@qvac/rag/errors' - -if (err instanceof QvacErrorRAG && err.code === ERR_CODES.OPERATION_CANCELLED) { - // handle cancellation -} -``` - -Existing `import { ERR_CODES } from "@qvac/rag"` continues to work unchanged. +- Load RAG hard dependencies (`hyperdb`, `hyperschema`, `llm-splitter`, `#fetch`) via synchronous `require()` instead of dynamic `await import()` for Pear/CJS compatibility (#2284). ## [0.6.0] -๐Ÿ“ฆ **NPM:** https://www.npmjs.com/package/@qvac/rag/v/0.6.0 - -This release completes the HyperDB 6 migration for `@qvac/rag`, aligning with the published `@qvac/registry-schema@0.3.0` and `@qvac/registry-client@0.6.0` stack. RAG now owns the Holepunch libraries it imports at runtime as direct dependencies instead of optional peers. The public RAG API is unchanged. - ---- - -## ๐Ÿ”ง Changed - -### HyperDB 6 and regenerated specs (#2255) - -`hyperdb` is bumped from the HyperDB 4 peer range to `^6.7.0` as a direct dependency. The autogenerated HyperDB spec under `src/adapters/database/hyperspec/` is rebuilt with the HyperDB 6 compiler output. +### Changed -### Dependency graph cleanup - -Runtime imports (`bare-crypto`, `bare-fetch`, `hyperdb`, `hyperdht`, `hyperschema`, `llm-splitter`) move from `peerDependencies` back to direct `dependencies` โ€” matching the registry hyperdb v6 cascade and avoiding peer-range drift when installed alongside `@qvac/sdk`. The `@qvac/registry-client` dev dependency is bumped to `^0.6.0` for examples and integration tests. +- Upgrade to HyperDB 6 (`hyperdb@^6.7.0`), regenerate RAG HyperDB specs for the v6 toolchain, and move runtime Holepunch libraries from `peerDependencies` to direct `dependencies` (#2255). +- Bump `@qvac/registry-client` dev dependency to `^0.6.0`. ## [0.5.0] -๐Ÿ“ฆ **NPM:** https://www.npmjs.com/package/@qvac/rag/v/0.5.0 - -This release makes `@qvac/rag` a first-class citizen in non-Bare runtimes โ€” React Native and Expo bundlers no longer choke on Bare-specific imports โ€” and tightens the package's place in the SDK install graph so Holepunch singletons (DHT, Corestore, HyperDB) are no longer duplicated in consumer trees. It also lands a small but real bug fix in RAG's crypto-fallback error path so consumers can finally catch missing-dependency errors by code. - ---- - -## ๐Ÿž Fixes - -### React Native / Expo bundling: `LLMChunkAdapter` is exported again - -Previously, importing `@qvac/rag` from a React Native or Expo project failed with `SyntaxError: 'LLMChunkAdapter' not exported` even though the export was present in the source โ€” the bundler was getting corrupted output because RAG's source had hard `bare-crypto` and `bare-fetch` imports that non-Bare bundlers tried (and failed) to resolve. - -Bare-specific dependencies are now routed through Node.js `package.json#imports` so the right module is selected per runtime: +### Fixed -- `#crypto` resolves to `bare-crypto` on Bare, `node:crypto` on Node, and a lazy shim on React Native and other targets. -- `#fetch` resolves to `bare-fetch` on Bare and a lazy shim on Node, React Native, and other targets. +- React Native / Expo bundling: routed `bare-crypto` and `bare-fetch` through `package.json#imports` (`#crypto`, `#fetch`) with lazy shims, so non-Bare bundlers no longer corrupt the package output (e.g. `SyntaxError: 'LLMChunkAdapter' not exported`). Missing capabilities now throw `QvacErrorRAG { DEPENDENCY_REQUIRED }` only when invoked. +- `generateId()` no longer mutates a global `crypto` or depends on `uuid-random`; UUID v4s are generated locally using secure randomness from `globalThis.crypto.getRandomValues` or `#crypto.randomBytes` / `getRandomValues`. +- `QvacErrorRAG` construction in RAG crypto fallbacks now uses the canonical `{ code, adds }` options object so the documented `DEPENDENCY_REQUIRED` (14015) error code is actually thrown (previously degraded to code `0` / `"Unknown QVAC error"`). -The shims allow bundling to succeed and only throw `QvacErrorRAG { DEPENDENCY_REQUIRED }` if the missing capability is actually invoked at runtime. Consumers on browsers, React Native, or Node who need Node-style `crypto.createHash` (notably for HyperDB document hashing) can install `crypto-browserify`, which is now declared as an **optional peer dependency**. +### Changed -`generateId()` no longer mutates a global `crypto` or depends on `uuid-random`. It generates UUID v4 IDs locally using secure randomness from `globalThis.crypto.getRandomValues` or `#crypto.randomBytes` / `getRandomValues`, and throws a clear error if neither is available. +- Holepunch singletons (`hyperdb`, `hyperdht`, `hyperschema`, `bare-crypto`, `bare-fetch`, `llm-splitter`) moved from `dependencies` to `peerDependencies` so consumer trees install a single copy aligned with `@qvac/sdk`'s ranges. `hyperdht` is marked optional (reserved for the unwired `replicateWith` path). +- Examples and integration tests migrated off `@qvac/dl-hyperdrive` to `@qvac/registry-client` (files-based addon construction). `devDependencies` updated accordingly: removed `@qvac/dl-hyperdrive`, added `@qvac/registry-client@^0.4.1`, bumped `@qvac/embed-llamacpp` `^0.7.6 โ†’ ^0.14.0` and `@qvac/llm-llamacpp` `^0.5.7 โ†’ ^0.16.0`. -### `QvacErrorRAG` in crypto fallbacks now reports the correct error code +### Added -Two RAG crypto-fallback call sites were constructing `QvacErrorRAG` with positional arguments `(code, message)` instead of the canonical `{ code, adds }` options object. Because `QvacErrorBase` destructures its single options argument, the thrown error silently degraded to code `0` / `"Unknown QVAC error"` instead of the intended `DEPENDENCY_REQUIRED` (14015) โ€” so consumers catching by code never matched. Both call sites in `helper.js` and `HyperDBAdapter.js` now use the canonical form, and the documented error code is what's actually thrown. - ---- - -## ๐Ÿงน Maintenance - -### Holepunch singletons moved to `peerDependencies` - -`@qvac/rag` previously declared `hyperdb`, `hyperdht`, `hyperschema`, `bare-crypto`, `bare-fetch`, and `llm-splitter` as hard dependencies. When the SDK declared its own (drifting) ranges for these as peers, npm could end up installing duplicate copies of stateful singletons in a consumer's tree โ€” separate DHT nodes, separate Corestores, broken P2P connectivity. These libraries are now `peerDependencies` (mirrored in `devDependencies` so the package still builds and tests in isolation), and `@qvac/sdk` is the single source of truth for the actual installed range. `hyperdht` is marked optional in RAG since it is reserved for the not-yet-wired `replicateWith` path. - -Consumers using `@qvac/sdk` or any tooling that auto-installs required peers (npm 7+, pnpm, bun) are unaffected โ€” the peers resolve transparently. Direct standalone consumers of `@qvac/rag` using `yarn` or `legacy-peer-deps=true` may now see missing-peer warnings and should add `hyperdb`, `hyperschema`, and `bare-crypto` (and `bare-fetch` if used in a Bare runtime) to their own dependencies. - -### DataLoader cleanup: examples and integration tests off `@qvac/dl-hyperdrive` - -The RAG examples and integration test no longer depend on `@qvac/dl-hyperdrive`. Model fetching now goes through `@qvac/registry-client` (mirroring how the SDK and OCR addons consume the QVAC registry), and the addon construction has migrated from the old `HyperDriveDL` + loader-based shape to the current files-based shape (`{ files, config, logger, opts }`). - -To support this, `devDependencies` were updated: - -- Removed: `@qvac/dl-hyperdrive` -- Added: `@qvac/registry-client@^0.4.1` -- Bumped: `@qvac/embed-llamacpp` `^0.7.6 โ†’ ^0.14.0`, `@qvac/llm-llamacpp` `^0.5.7 โ†’ ^0.16.0` (versions that ship the files-based API). - -This is purely a developer-facing change โ€” runtime behavior of `@qvac/rag` is unchanged. The SDK-side `overrides: { @qvac/dl-hyperdrive: ^0.2.0 }` is intentionally retained until the addons-side cleanup of `@qvac/infer-base`'s `dl-hyperdrive` peer dep lands. +- `crypto-browserify` as an optional peer dependency for browser / React Native consumers that need Node-style `crypto.createHash` (notably for HyperDB document hashing). ## [0.4.4] -๐Ÿ“ฆ **NPM:** https://www.npmjs.com/package/@qvac/rag/v/0.4.4 - -This release focuses on dependency hygiene and package namespace consistency for the RAG library. It aligns documentation with the `@qvac` npm scope and updates core crypto dependency declarations to match current runtime expectations. - ---- - -## ๐Ÿ“˜ Documentation +### Changed -README references have been updated from the legacy `@tetherto` namespace to `@qvac`, reducing installation confusion and ensuring examples match currently published package names. +- README: replaced `@tetherto` npm references with `@qvac` namespace references. +- Dependencies: bumped `bare-crypto` to `^1.13.4` and cleaned up RAG package dependency declarations. ---- +## [0.4.3] -## ๐Ÿงน Maintenance +### Changed -`bare-crypto` dependency declarations were updated to `^1.13.4`, and related `package.json` cleanup was applied in the RAG package. This keeps dependency metadata aligned with the current SDK pod ecosystem and reduces drift across package manifests. +- README: removed outdated npm Personal Access Token / `.npmrc` setup instructions for installing `@qvac/rag`. From 13ee41b77f372f8feae6ff320753ea1bc9b4bcea Mon Sep 17 00:00:00 2001 From: opaninakuffo Date: Mon, 24 Aug 2026 11:53:13 +0000 Subject: [PATCH 3/3] chore[notask]: bump @qvac/rag error metadata version to 0.7.0 Keep errors.ts lockstep with package.json so the unit test passes. --- packages/rag/src/errors.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/rag/src/errors.ts b/packages/rag/src/errors.ts index 71629c3d8b..a8fbefe065 100644 --- a/packages/rag/src/errors.ts +++ b/packages/rag/src/errors.ts @@ -98,4 +98,4 @@ const definitions: ErrorCodesMap = { } } -addCodes(definitions, { name: '@qvac/rag', version: '0.6.4' }) +addCodes(definitions, { name: '@qvac/rag', version: '0.7.0' })