Skip to content

fix(rag): preserve JSON format metadata in JsonChunker - #1463

Open
Jun516 wants to merge 1 commit into
VoltAgent:mainfrom
Jun516:fix/rag-preserve-json-format-metadata
Open

Jun516 wants to merge 1 commit into
VoltAgent:mainfrom
Jun516:fix/rag-preserve-json-format-metadata

Conversation

@Jun516

@Jun516 Jun516 commented Oct 18, 2026 •

Copy link
Copy Markdown

Summary

JsonChunker first tokenizes its flattened JSON representation, then wraps the token chunks with JSON-specific metadata. The inherited token metadata contains format: "text", and buildMetadata merges the inherited extras last, overwriting the intended format: "json". Valid JSON chunks therefore silently report the wrong format even though sourceType is JSON and structural fields are present.

This PR removes the inherited format and sourceType keys before merging token chunk metadata. It retains token positions and JSON structural metadata, while invalid JSON still falls back to token chunking with format: "text".

Changes

  • Exclude the inner TokenChunker's format and sourceType from JsonChunker's extras.
  • Assert JSON format/source type on parsed JSON and text/token metadata on the invalid-JSON fallback.
  • Add a patch Changeset for @voltagent/rag.

Reproduction and validation

  • Examined the current upstream main source at 72a46c76b4507e1f98b41d5050a92bd30587eb70.
  • Isolated TypeScript harness recreated the reviewed JsonChunker, TokenChunker, and buildMetadata implementations, substituting only minimal tokenization/position helpers because the complete monorepo dependencies were unavailable.
  • Before fix: valid JSON produces format: "text"; the targeted assertion fails.
  • After fix: TypeScript compilation and targeted assertions pass for valid JSON (json/json) and invalid JSON fallback (text/token).
  • Patch verified to apply cleanly to the reviewed source snapshot and passed git diff --check.

Not run: official monorepo Vitest, package TypeScript build, lint, full CI, and integration tests. These still need real execution in the upstream/fork CI environment. The isolated harness is not a substitute for official tests.

Scope and prior work

Independent of #1459, which changes detectFormat routing for top-level arrays; this PR fixes metadata produced after a valid JSON payload has already reached JsonChunker.

AI use

Prepared with AI-assisted source review, duplication search, isolated reproduction, and patch verification. All validation limits are documented above.


Summary by cubic

Fixes JsonChunker metadata so valid JSON chunks report format: "json" and sourceType: "json" instead of inheriting "text"/"token" from the inner token chunker.

  • Strips the token chunk's format and sourceType before merging JSON metadata, while keeping token positions and structural fields.
  • Adds assertions covering the JSON metadata path and the invalid-JSON fallback, plus a patch Changeset for @voltagent/rag.

Written for commit 146be7c. Summary will update on new commits.

View guided diff

Summary by CodeRabbit

  • Bug Fixes
    • JSON chunks now preserve their format and source type metadata, including when the input contains invalid JSON. This keeps information about the original content available alongside chunks produced by the JSON chunker.

@changeset-bot

changeset-bot Bot commented Oct 18, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 146be7c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@voltagent/rag Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@coderabbitai

coderabbitai Bot commented Oct 18, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 78c67023-1b30-4383-93d9-46dad4f33cec
📥 Commits

Reviewing files that changed from the base of the PR and between 72a46c7 and 146be7c.

📒 Files selected for processing: 3
  • .changeset/calm-otters-json-format.md
  • packages/rag/src/__tests__/json-chunker.spec.ts
  • packages/rag/src/chunkers/json-chunker.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

📝 Walkthrough

JsonChunker now excludes both format and sourceType from extra metadata when building chunk metadata. Tests check the metadata for valid and invalid JSON, and a patch changeset records the update.

Changes: JSON Chunk Metadata

Layer / File(s) Summary
Preserve JSON chunk metadata
packages/rag/src/chunkers/json-chunker.ts, packages/rag/src/__tests__/json-chunker.spec.ts, .changeset/calm-otters-json-format.md
JsonChunker excludes format and sourceType from chunkExtra. Tests assert the expected metadata for valid and invalid JSON. A patch changeset describes the update.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~7 minutes

Change: Bug fix

Suggested reviewers: omeraplak

Merge Risk: ⚪ Minimal · up to 146be

Valid JSON chunks retain JSON format and source metadata, while invalid input keeps the token fallback metadata. The implementation matches the intended behavior, with no concrete merge blocker identified.

Pre-merge checks: Passed 5
Check name Status Explanation
Title check Passed The title clearly and concisely describes the primary change: preserving JSON format metadata in JsonChunker.
Description check Passed The description clearly explains the current defect, the new behavior, implementation changes, tests, changeset, validation limits, and scope. It does not use every template heading or provide a linke…
Docstring Coverage Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Description check

Explanation

The description clearly explains the current defect, the new behavior, implementation changes, tests, changeset, validation limits, and scope. It does not use every template heading or provide a linked issue, but it contains the required information in equivalent sections.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2 files. (1 skipped: 1 unsupported.)

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1 issue found across 3 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/rag/src/__tests__/json-chunker.spec.ts">

<violation number="1" location="packages/rag/src/__tests__/json-chunker.spec.ts:12">
P3: The new assertions cover `format` and `sourceType` but not the token position fields this PR says it preserves. Add a `tokenStart` assertion on the parsed-JSON chunk so a regression that drops it gets caught.</violation>
</file>

Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic

expect(chunks.length).toBeGreaterThan(0);
expect(chunks[0]?.metadata?.fields).toBeGreaterThan(0);
expect(chunks[0]?.metadata?.format).toBe("json");
expect(chunks[0]?.metadata?.sourceType).toBe("json");

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: The new assertions cover format and sourceType but not the token position fields this PR says it preserves. Add a tokenStart assertion on the parsed-JSON chunk so a regression that drops it gets caught.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/rag/src/__tests__/json-chunker.spec.ts, line 12:

<comment>The new assertions cover `format` and `sourceType` but not the token position fields this PR says it preserves. Add a `tokenStart` assertion on the parsed-JSON chunk so a regression that drops it gets caught.</comment>

<file context>
@@ -8,11 +8,15 @@ describe("JsonChunker", () => {
     expect(chunks.length).toBeGreaterThan(0);
     expect(chunks[0]?.metadata?.fields).toBeGreaterThan(0);
+    expect(chunks[0]?.metadata?.format).toBe("json");
+    expect(chunks[0]?.metadata?.sourceType).toBe("json");
   });
 
</file context>
Suggested change
expect(chunks[0]?.metadata?.sourceType).toBe("json");
expect(chunks[0]?.metadata?.sourceType).toBe("json");
expect(chunks[0]?.metadata?.tokenStart).toBe(0);

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant