@mastra/rag 2.4.0-alpha.0 → 2.4.1-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @mastra/rag
 
+## 2.4.1-alpha.0
+
+### Patch Changes
+
+- Fixed token chunking to reject overlaps that cannot advance. ([#19213](https://github.com/mastra-ai/mastra/pull/19213))
+
+- Fixed RAG rerank observability spans to record scoring failures before rethrowing. ([#19246](https://github.com/mastra-ai/mastra/pull/19246))
+
+- Fixed RAG filter parsing to reject JSON string filters that parse to non-object values. ([#19244](https://github.com/mastra-ai/mastra/pull/19244))
+
+- Fixed Mastra agent relevance scoring to reject invalid model score output. ([#19251](https://github.com/mastra-ai/mastra/pull/19251))
+
+- Fixed character chunking to preserve content with custom length functions. ([#19214](https://github.com/mastra-ai/mastra/pull/19214))
+
+- Fixed Cohere relevance scoring to use COHERE_API_KEY by default and accept zero relevance scores. ([#19238](https://github.com/mastra-ai/mastra/pull/19238))
+
+- Updated dependencies [[`a5c6337`](https://github.com/mastra-ai/mastra/commit/a5c6337d23c7686c81a32ce62f550f610543a240), [`8b97958`](https://github.com/mastra-ai/mastra/commit/8b979589f9aa59ba67cac565949475f2ffeb4ac3), [`8410541`](https://github.com/mastra-ai/mastra/commit/84105412c60ecd3bb33a9838146f59c4b588228f), [`01b338c`](https://github.com/mastra-ai/mastra/commit/01b338c56271f0219606710e3e8b26dee27ac6c2), [`8b7361d`](https://github.com/mastra-ai/mastra/commit/8b7361d35de68b80d05d30a74e0c69e7218fd612), [`c43f3a9`](https://github.com/mastra-ai/mastra/commit/c43f3a9d1efde99b38789364ba4d0ba670f430e3)]:
+  - @mastra/core@1.51.0-alpha.4
+
+## 2.4.0
+
+### Minor Changes
+
+- Added MongoDBConfig to DatabaseConfig, exposing numCandidates for MongoDB Atlas Vector Search queries via the RAG tool layer. ([#18393](https://github.com/mastra-ai/mastra/pull/18393))
+
+### Patch Changes
+
+- Updated dependencies [[`b9a2961`](https://github.com/mastra-ai/mastra/commit/b9a2961c1be81e3639c0879e58588c26dd0ae866), [`b33c77d`](https://github.com/mastra-ai/mastra/commit/b33c77d5293f14a794f3ec38dc947a6676de2764), [`1274eb3`](https://github.com/mastra-ai/mastra/commit/1274eb3a9508f579ceb3187fbce34408222d4b71), [`cdd5f93`](https://github.com/mastra-ai/mastra/commit/cdd5f939cefa67390629704dce92563ccbf492b2), [`1274eb3`](https://github.com/mastra-ai/mastra/commit/1274eb3a9508f579ceb3187fbce34408222d4b71), [`0ac14ce`](https://github.com/mastra-ai/mastra/commit/0ac14cea48e1b0a7857782153c78f7242fdf7e1a), [`9566d27`](https://github.com/mastra-ai/mastra/commit/9566d27ead3d95bdbe5a69e5a082a68222829cf2), [`8be63b0`](https://github.com/mastra-ai/mastra/commit/8be63b015fb8d72cea1220f05e7dc3bb997cc249), [`1009f77`](https://github.com/mastra-ai/mastra/commit/1009f772aa40016b49267c8566d0c29f6a16aa3c), [`1b8728a`](https://github.com/mastra-ai/mastra/commit/1b8728a57fd844205a452b0b4216d20ff60c784a), [`23c31de`](https://github.com/mastra-ai/mastra/commit/23c31de96ed8153402dcf092ac84b27a0c3638c1), [`0368766`](https://github.com/mastra-ai/mastra/commit/0368766744c7ea3df4d6059e2cc15f7bdf55f5a6), [`6f578ac`](https://github.com/mastra-ai/mastra/commit/6f578acba84930b406b2a0700b17cfdfaf5aae56), [`345eecc`](https://github.com/mastra-ai/mastra/commit/345eecce6ba519b5d987f0e10b5de4c8e5734580), [`1917c53`](https://github.com/mastra-ai/mastra/commit/1917c53b19dac43926f29c496893b0686462dca4), [`c01012f`](https://github.com/mastra-ai/mastra/commit/c01012f50368d29eb3fc3764df42d48291973d23), [`705ba98`](https://github.com/mastra-ai/mastra/commit/705ba98726d388a596e896225f237907ca6807a9), [`95857bc`](https://github.com/mastra-ai/mastra/commit/95857bcd6669da7193f503e803f0d72a2bd66be6), [`e62c108`](https://github.com/mastra-ai/mastra/commit/e62c108409dfd6a6cac0a48ec39c5cc81d24fd52), [`2866f04`](https://github.com/mastra-ai/mastra/commit/2866f04953edb78c1637fa45cc53abe24122edcb), [`ee14cae`](https://github.com/mastra-ai/mastra/commit/ee14cae244805783bde518a6142de28b744b169c), [`e84e791`](https://github.com/mastra-ai/mastra/commit/e84e79174031d7bc8793ca6c805eb38b06e7cfb1), [`c2f0b7f`](https://github.com/mastra-ai/mastra/commit/c2f0b7f1370f4428d165f51f0d1d9a48331cc257), [`213feb8`](https://github.com/mastra-ai/mastra/commit/213feb87bfdd1d8ec00ea660e218f9bcfcb34e7b), [`58e287b`](https://github.com/mastra-ai/mastra/commit/58e287b1edaf978b13745a1795989cad3826e82b), [`e420b3c`](https://github.com/mastra-ai/mastra/commit/e420b3c3ffc98bbc5b791897ea390bb47af99696), [`be875ed`](https://github.com/mastra-ai/mastra/commit/be875ed43f856742ce58529f531b5ea0ae6911f3), [`9eefdc0`](https://github.com/mastra-ai/mastra/commit/9eefdc0ac03f989718c6d835334940a977938895), [`bfbbb01`](https://github.com/mastra-ai/mastra/commit/bfbbb01bd845ba54cdc0c678c277d08a7cb847e4), [`7d112ca`](https://github.com/mastra-ai/mastra/commit/7d112ca17078479b2659b88ba1c85b936cfc111c)]:
+  - @mastra/core@1.48.0
+
 ## 2.4.0-alpha.0
 
 ### Minor Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-rag
 description: Documentation for @mastra/rag. Use when working with @mastra/rag APIs, configuration, or implementation.
 metadata:
   package: "@mastra/rag"
-  version: "2.4.0-alpha.0"
+  version: "2.4.1-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.4.0-alpha.0",
+  "version": "2.4.1-alpha.0",
   "package": "@mastra/rag",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-rag-chunking-and-embedding.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Chunking and embedding documents
 
 Before processing, create a MDocument instance from your content. You can initialize it from various formats:

package/dist/docs/references/docs-rag-graph-rag.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # GraphRAG
 
 Graph-based retrieval enhances traditional vector search by following relationships between chunks of information. This approach is useful when information is spread across multiple documents or when documents reference each other.

package/dist/docs/references/docs-rag-overview.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # RAG (Retrieval-Augmented Generation) in Mastra
 
 RAG in Mastra helps you enhance LLM outputs by incorporating relevant context from your own data sources, improving accuracy and grounding responses in real information.

package/dist/docs/references/docs-rag-retrieval.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Retrieval in RAG systems
 
 After storing embeddings, you need to retrieve relevant chunks to answer user queries.

package/dist/docs/references/reference-rag-chunk.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # .chunk()
 
 The `.chunk()` function splits documents into smaller segments using various strategies and options.
@@ -176,9 +178,9 @@ The options documented below are passed directly at the top level of the configu
 
 **joinThreshold** (`number`): Maximum token count for merging related sections. Sections exceeding this limit individually are left intact, but smaller sections are merged with siblings or parents if the combined size stays under this threshold. (Default: `500`)
 
-**modelName** (`string`): Name of the model for tokenization. If provided, the model's underlying tokenization \`encodingName\` will be used.
+**modelName** (`string`): Name of the model for tokenization. If provided, the model's underlying tokenization encodingName will be used.
 
-**encodingName** (`string`): Name of the token encoding to use. Derived from \`modelName\` if available. (Default: `cl100k_base`)
+**encodingName** (`string`): Name of the token encoding to use. Derived from modelName if available. (Default: `cl100k_base`)
 
 **allowedSpecial** (`Set<string> | 'all'`): Set of special tokens allowed during tokenization, or 'all' to allow all special tokens
 

package/dist/docs/references/reference-rag-database-config.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # DatabaseConfig
 
 The `DatabaseConfig` type allows you to specify database-specific configurations when using vector query tools. These configurations enable you to leverage unique features and optimizations offered by different vector stores.

package/dist/docs/references/reference-rag-document.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # MDocument
 
 The MDocument class processes documents for RAG applications. The main methods are `.chunk()` and `.extractMetadata()`.

package/dist/docs/references/reference-rag-extract-params.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # ExtractParams
 
 ExtractParams configures metadata extraction from document chunks using LLM analysis.

package/dist/docs/references/reference-rag-graph-rag.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # GraphRAG
 
 The `GraphRAG` class implements a graph-based approach to retrieval augmented generation. It creates a knowledge graph from document chunks where nodes represent documents and edges represent semantic relationships, enabling both direct similarity matching and discovery of related content through graph traversal.

package/dist/docs/references/reference-rag-rerank.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # rerank()
 
 The `rerank()` function provides advanced reranking capabilities for vector search results by combining semantic relevance, vector similarity, and position-based scoring.

package/dist/docs/references/reference-rag-rerankWithScorer.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # rerankWithScorer()
 
 The `rerankWithScorer()` function provides advanced reranking capabilities for vector search results by combining semantic relevance, vector similarity, and position-based scoring.

package/dist/docs/references/reference-tools-document-chunker-tool.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # createDocumentChunkerTool()
 
 The `createDocumentChunkerTool()` function creates a tool for splitting documents into smaller chunks for efficient processing and retrieval. It supports different chunking strategies and configurable parameters.

package/dist/docs/references/reference-tools-graph-rag-tool.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # createGraphRAGTool()
 
 The `createGraphRAGTool()` creates a tool that enhances RAG by building a graph of semantic relationships between documents. It uses the `GraphRAG` system under the hood to provide graph-based retrieval, finding relevant content through both direct similarity and connected relationships.
@@ -51,7 +53,7 @@ const graphTool = createGraphRAGTool({
 
 **providerOptions** (`Record<string, Record<string, any>>`): Provider-specific options for the embedding model (e.g., outputDimensionality). \*\*Important\*\*: Only works with AI SDK EmbeddingModelV2 models. For V1 models, configure options when creating the model itself.
 
-**vectorStore** (`MastraVector | VectorStoreResolver`): Direct vector store instance or a resolver function for dynamic selection. Use a function for multi-tenant applications where the vector store is selected based on request context. When provided, \`vectorStoreName\` becomes optional.
+**vectorStore** (`MastraVector | VectorStoreResolver`): Direct vector store instance or a resolver function for dynamic selection. Use a function for multi-tenant applications where the vector store is selected based on request context. When provided, vectorStoreName becomes optional.
 
 ## Returns
 

package/dist/docs/references/reference-tools-vector-query-tool.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # createVectorQueryTool()
 
 The `createVectorQueryTool()` function creates a tool for semantic search over vector stores. It supports filtering, reranking, database-specific configurations, and integrates with various vector store backends.
@@ -69,7 +71,7 @@ const queryTool = createVectorQueryTool({
 
 **providerOptions** (`Record<string, Record<string, any>>`): Provider-specific options for the embedding model (e.g., outputDimensionality). \*\*Important\*\*: Only works with AI SDK EmbeddingModelV2 models. For V1 models, configure options when creating the model itself.
 
-**vectorStore** (`MastraVector | VectorStoreResolver`): Direct vector store instance or a resolver function for dynamic selection. Use a function for multi-tenant applications where the vector store is selected based on request context. When provided, \`vectorStoreName\` becomes optional.
+**vectorStore** (`MastraVector | VectorStoreResolver`): Direct vector store instance or a resolver function for dynamic selection. Use a function for multi-tenant applications where the vector store is selected based on request context. When provided, vectorStoreName becomes optional.
 
 ## Returns
 

package/dist/document/transformers/character.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"character.d.ts","sourceRoot":"","sources":["../../../src/document/transformers/character.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAE/F,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AA+CzC,qBAAa,oBAAqB,SAAQ,eAAe;IACvD,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,gBAAgB,EAAE,OAAO,CAAC;gBAExB,EAAE,SAAkB,EAAE,gBAAwB,EAAE,GAAG,WAAW,EAAE,GAAE,qBAA0B;IAMxG,SAAS,CAAC,EAAE,IAAI,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,EAAE;IAqB/C,OAAO,CAAC,YAAY;CAyBrB;AAED,qBAAa,6BAA8B,SAAQ,eAAe;IAChE,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;IAC/B,SAAS,CAAC,gBAAgB,EAAE,OAAO,CAAC;gBAExB,EAAE,UAAU,EAAE,gBAAwB,EAAE,QAAQ,EAAE,GAAG,WAAW,EAAE,GAAE,qBAA0B;IAM1G,OAAO,CAAC,UAAU;IAuDlB,SAAS,CAAC,EAAE,IAAI,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,EAAE;IAI/C,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,GAAE,gBAAqB,GAAG,6BAA6B;IAUtG,MAAM,CAAC,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,EAAE;CAwa9D"}
+{"version":3,"file":"character.d.ts","sourceRoot":"","sources":["../../../src/document/transformers/character.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAE/F,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AA+CzC,qBAAa,oBAAqB,SAAQ,eAAe;IACvD,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,gBAAgB,EAAE,OAAO,CAAC;gBAExB,EAAE,SAAkB,EAAE,gBAAwB,EAAE,GAAG,WAAW,EAAE,GAAE,qBAA0B;IAMxG,SAAS,CAAC,EAAE,IAAI,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,EAAE;IAqB/C,OAAO,CAAC,YAAY;CAyDrB;AAED,qBAAa,6BAA8B,SAAQ,eAAe;IAChE,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC;IAC/B,SAAS,CAAC,gBAAgB,EAAE,OAAO,CAAC;gBAExB,EAAE,UAAU,EAAE,gBAAwB,EAAE,QAAQ,EAAE,GAAG,WAAW,EAAE,GAAE,qBAA0B;IAM1G,OAAO,CAAC,UAAU;IAuDlB,SAAS,CAAC,EAAE,IAAI,EAAE,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,EAAE;IAI/C,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,GAAE,gBAAqB,GAAG,6BAA6B;IAUtG,MAAM,CAAC,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,EAAE;CAwa9D"}

package/dist/index.cjs

@@ -4537,8 +4537,8 @@ var TextTransformer = class {
     addStartIndex = false,
     stripWhitespace = true
   }) {
-    if (overlap > maxSize) {
-      throw new Error(`Got a larger chunk overlap (${overlap}) than chunk size (${maxSize}), should be smaller.`);
+    if (overlap >= maxSize) {
+      throw new Error(`Chunk overlap (${overlap}) must be smaller than chunk size (${maxSize}).`);
     }
     this.maxSize = maxSize;
     this.overlap = overlap;
@@ -4707,17 +4707,31 @@ var CharacterTransformer = class extends TextTransformer {
   }
   __splitChunk(text) {
     const chunks = [];
-    let currentPosition = 0;
-    while (currentPosition < text.length) {
-      let chunkEnd = currentPosition;
-      while (chunkEnd < text.length && this.lengthFunction(text.slice(currentPosition, chunkEnd + 1)) <= this.maxSize) {
-        chunkEnd++;
-      }
-      const currentChunk = text.slice(currentPosition, chunkEnd);
-      const chunkLength = this.lengthFunction(currentChunk);
+    const codePointBoundaries = [0];
+    for (const codePoint of text) {
+      codePointBoundaries.push(codePointBoundaries[codePointBoundaries.length - 1] + codePoint.length);
+    }
+    const finalBoundaryIndex = codePointBoundaries.length - 1;
+    let currentBoundaryIndex = 0;
+    while (currentBoundaryIndex < finalBoundaryIndex) {
+      let chunkEndBoundaryIndex = currentBoundaryIndex;
+      while (chunkEndBoundaryIndex < finalBoundaryIndex && this.lengthFunction(
+        text.slice(codePointBoundaries[currentBoundaryIndex], codePointBoundaries[chunkEndBoundaryIndex + 1])
+      ) <= this.maxSize) {
+        chunkEndBoundaryIndex++;
+      }
+      if (chunkEndBoundaryIndex === currentBoundaryIndex) {
+        chunkEndBoundaryIndex++;
+      }
+      const chunkEnd = codePointBoundaries[chunkEndBoundaryIndex];
+      const currentChunk = text.slice(codePointBoundaries[currentBoundaryIndex], chunkEnd);
       chunks.push(currentChunk);
-      if (chunkEnd >= text.length) break;
-      currentPosition += Math.max(1, chunkLength - this.overlap);
+      if (chunkEndBoundaryIndex >= finalBoundaryIndex) break;
+      let nextBoundaryIndex = chunkEndBoundaryIndex;
+      while (this.overlap > 0 && nextBoundaryIndex > currentBoundaryIndex && this.lengthFunction(text.slice(codePointBoundaries[nextBoundaryIndex - 1], chunkEnd)) <= this.overlap) {
+        nextBoundaryIndex--;
+      }
+      currentBoundaryIndex = Math.max(currentBoundaryIndex + 1, nextBoundaryIndex);
     }
     return chunks;
   }
@@ -6976,10 +6990,13 @@ var CohereRelevanceScorer = class {
   model;
   apiKey;
   constructor(model, apiKey) {
-    this.apiKey = apiKey;
+    this.apiKey = apiKey ?? process.env.COHERE_API_KEY;
     this.model = model;
   }
   async getRelevanceScore(query, text) {
+    if (!this.apiKey) {
+      throw new Error("Cohere API key is required. Pass an apiKey or set COHERE_API_KEY.");
+    }
     const response = await fetch(`https://api.cohere.com/v2/rerank`, {
       method: "POST",
       headers: {
@@ -6998,12 +7015,20 @@ var CohereRelevanceScorer = class {
     }
     const data = await response.json();
     const relevanceScore = data.results[0]?.relevance_score;
-    if (!relevanceScore) {
+    if (typeof relevanceScore !== "number" || !Number.isFinite(relevanceScore)) {
       throw new Error("No relevance score found on Cohere response");
     }
     return relevanceScore;
   }
 };
+function parseRelevanceScore(responseText) {
+  const trimmed = responseText.trim();
+  const score = Number(trimmed);
+  if (!trimmed || !Number.isFinite(score) || score < 0 || score > 1) {
+    throw new Error(`Invalid relevance score returned by model: ${responseText}`);
+  }
+  return score;
+}
 var MastraAgentRelevanceScorer = class {
   agent;
   constructor(name14, model) {
@@ -7032,7 +7057,7 @@ Always return just the number, no explanation.`,
     } else {
       response = await this.agent.generateLegacy(prompt);
     }
-    return parseFloat(response.text);
+    return parseRelevanceScore(response.text);
   }
 };
 var ZeroEntropyRelevanceScorer = class {
@@ -7104,35 +7129,41 @@ async function executeRerank({
   }
   const resultLength = results.length;
   const queryAnalysis = queryEmbedding ? analyzeQueryEmbedding(queryEmbedding) : null;
-  const scoredResults = await Promise.all(
-    results.map(async (result, index) => {
-      let semanticScore = 0;
-      if (result?.metadata?.text) {
-        semanticScore = await scorer.getRelevanceScore(query, result?.metadata?.text);
-      }
-      const vectorScore = result.score;
-      const positionScore = calculatePositionScore(index, resultLength);
-      let finalScore = weights.semantic * semanticScore + weights.vector * vectorScore + weights.position * positionScore;
-      if (queryAnalysis) {
-        finalScore = adjustScores(finalScore, queryAnalysis);
-      }
-      return {
-        result,
-        score: finalScore,
-        details: {
-          semantic: semanticScore,
-          vector: vectorScore,
-          position: positionScore,
-          ...queryAnalysis && {
-            queryAnalysis: {
-              magnitude: queryAnalysis.magnitude,
-              dominantFeatures: queryAnalysis.dominantFeatures
+  let scoredResults;
+  try {
+    scoredResults = await Promise.all(
+      results.map(async (result, index) => {
+        let semanticScore = 0;
+        if (result?.metadata?.text) {
+          semanticScore = await scorer.getRelevanceScore(query, result?.metadata?.text);
+        }
+        const vectorScore = result.score;
+        const positionScore = calculatePositionScore(index, resultLength);
+        let finalScore = weights.semantic * semanticScore + weights.vector * vectorScore + weights.position * positionScore;
+        if (queryAnalysis) {
+          finalScore = adjustScores(finalScore, queryAnalysis);
+        }
+        return {
+          result,
+          score: finalScore,
+          details: {
+            semantic: semanticScore,
+            vector: vectorScore,
+            position: positionScore,
+            ...queryAnalysis && {
+              queryAnalysis: {
+                magnitude: queryAnalysis.magnitude,
+                dominantFeatures: queryAnalysis.dominantFeatures
+              }
             }
           }
-        }
-      };
-    })
-  );
+        };
+      })
+    );
+  } catch (err) {
+    rerankSpan?.error({ error: err, endSpan: true });
+    throw err;
+  }
   const final = scoredResults.sort((a, b) => b.score - a.score).slice(0, topK);
   rerankSpan?.end({ output: { returned: final.length } });
   return final;
@@ -7706,9 +7737,10 @@ function parseFilterValue(filter, logger) {
   if (!filter) {
     return {};
   }
+  let parsedFilter = filter;
   if (typeof filter === "string") {
     try {
-      return JSON.parse(filter);
+      parsedFilter = JSON.parse(filter);
     } catch (error) {
       if (logger) {
         logger.error("Invalid filter", { filter, error });
@@ -7716,15 +7748,14 @@ function parseFilterValue(filter, logger) {
       throw new Error(`Invalid filter format: ${error instanceof Error ? error.message : String(error)}`);
     }
   }
-  if (typeof filter !== "object" || filter === null || Array.isArray(filter)) {
+  if (typeof parsedFilter !== "object" || parsedFilter === null || Array.isArray(parsedFilter)) {
+    const receivedType = Array.isArray(parsedFilter) ? "array" : typeof parsedFilter;
     if (logger) {
       logger.error("Invalid filter", { filter, error: "Filter must be a plain object" });
     }
-    throw new Error(
-      `Invalid filter format: expected a plain object, got ${Array.isArray(filter) ? "array" : typeof filter}`
-    );
+    throw new Error(`Invalid filter format: expected a plain object, got ${receivedType}`);
   }
-  return filter;
+  return parsedFilter;
 }
 
 // src/utils/convert-sources.ts