@ontos-ai/knowhere-sdk 2.2.0-beta.20260716073420 → 2.3.0

package/README.md

@@ -423,6 +423,7 @@ const grep = await client.knowledge.grepChunks({
   pattern: 'warranty',
   maxResults: 10,
 });
+// grep.matches include pageNumbers when the source chunk has them.
 
 const serverSearch = await client.knowledge.search({
   query: 'battery warranty',
@@ -514,12 +515,17 @@ without creating SDK local-disk cache state. Use `syncParsedDocument(...)` to
 explicitly resume or retry parsed-storage sync for an existing `documentId`,
 `jobId`, or local parsed result.
 
-Follow-up queries can exclude documents or sections for one request:
+Retrieval queries can limit documents and exclude documents or sections for one request.
+`includeDocumentIds?: string[]` restricts retrieval to the supplied document IDs.
+Omitting it leaves documents unrestricted by inclusion; passing `[]` matches no
+documents. Exclusions take precedence over inclusions, including when a document
+ID appears in both `includeDocumentIds` and `excludeDocumentIds`.
 
 ```typescript
 const followUp = await client.retrieval.query({
   namespace: 'support-center',
   query: 'battery charging',
+  includeDocumentIds: ['doc_123', 'doc_old'],
   excludeDocumentIds: ['doc_old'],
   excludeSections: [{ documentId: 'doc_123', sectionPath: 'Appendix / Legal' }],
 });

package/dist/index.d.mts

@@ -859,7 +859,13 @@ interface RetrievalQueryParams {
     threshold?: number;
     /** Override the internal per-channel recall count */
     internalRecallK?: number;
-    /** Documents to exclude for this request only */
+    /**
+     * Limit retrieval to these documents for this request only.
+     * Omitted means no document inclusion restriction; [] matches no documents.
+     * Exclusions take precedence over inclusions.
+     */
+    includeDocumentIds?: string[];
+    /** Documents to exclude for this request only, even when included in includeDocumentIds. */
     excludeDocumentIds?: string[];
     /** Document sections to exclude for this request only */
     excludeSections?: RetrievalSectionExclusion[];
@@ -1355,6 +1361,8 @@ interface KnowledgeGrepMatch {
     startOffset: number;
     endOffset: number;
     snippet: string;
+    /** Copied from the source chunk when the indexed chunk has page numbers. */
+    pageNumbers?: number[];
 }
 interface KnowledgeGrepResponse {
     document: LocalKnowledgeDocument;

package/dist/index.d.ts

@@ -859,7 +859,13 @@ interface RetrievalQueryParams {
     threshold?: number;
     /** Override the internal per-channel recall count */
     internalRecallK?: number;
-    /** Documents to exclude for this request only */
+    /**
+     * Limit retrieval to these documents for this request only.
+     * Omitted means no document inclusion restriction; [] matches no documents.
+     * Exclusions take precedence over inclusions.
+     */
+    includeDocumentIds?: string[];
+    /** Documents to exclude for this request only, even when included in includeDocumentIds. */
     excludeDocumentIds?: string[];
     /** Document sections to exclude for this request only */
     excludeSections?: RetrievalSectionExclusion[];
@@ -1355,6 +1361,8 @@ interface KnowledgeGrepMatch {
     startOffset: number;
     endOffset: number;
     snippet: string;
+    /** Copied from the source chunk when the indexed chunk has page numbers. */
+    pageNumbers?: number[];
 }
 interface KnowledgeGrepResponse {
     document: LocalKnowledgeDocument;

package/dist/index.js

@@ -2614,17 +2614,7 @@ var Knowledge = class _Knowledge {
       scannedChunks += 1;
       const chunkMatches = matcher(chunk.content);
       for (const match of chunkMatches) {
-        matches.push({
-          position: chunk.position,
-          chunkId: chunk.chunkId,
-          chunkType: chunk.chunkType,
-          sectionPath: chunk.sectionPath,
-          sourceChunkPath: chunk.sourceChunkPath,
-          filePath: chunk.filePath,
-          startOffset: match.startOffset,
-          endOffset: match.endOffset,
-          snippet: buildSnippet(chunk.content, match.startOffset, match.endOffset, contextChars)
-        });
+        matches.push(toGrepMatch(chunk, match, contextChars));
         if (matches.length >= maxResults) {
           return { document, matches, scannedChunks, truncated: true };
         }
@@ -2638,7 +2628,8 @@ var Knowledge = class _Knowledge {
       query: params.query,
       namespace: params.namespace,
       topK: params.topK,
-      useAgentic: params.useAgentic ?? false
+      // Omit when undefined so the API default (map-nav) applies; false → classic.
+      useAgentic: params.useAgentic
     });
     const documentByServerId = new Map(
       localDocuments.filter((document) => document.documentId).map((document) => [document.documentId, document])
@@ -2855,31 +2846,17 @@ var Knowledge = class _Knowledge {
         if (response.pagination.page === startPage && cursor?.nextChunkIndex !== void 0 && chunkIndex < cursor.nextChunkIndex) {
           continue;
         }
-        if (!matchesGrepScope(toIndexedRemoteChunk(chunk), params)) {
+        const indexed = toIndexedRemoteChunk(chunk);
+        if (!matchesGrepScope(indexed, params)) {
           continue;
         }
         scannedChunks += 1;
-        const chunkMatches = matcher(chunk.content ?? "");
+        const chunkMatches = matcher(indexed.content);
         for (const [matchIndex, match] of chunkMatches.entries()) {
           if (response.pagination.page === startPage && cursor?.nextChunkIndex === chunkIndex && cursor.nextMatchIndex !== void 0 && matchIndex < cursor.nextMatchIndex) {
             continue;
           }
-          matches.push({
-            position: toChunkPosition(chunk),
-            chunkId: chunk.chunkId,
-            chunkType: chunk.chunkType,
-            sectionPath: chunk.sectionPath ?? "",
-            sourceChunkPath: chunk.sourceChunkPath ?? chunk.sectionPath ?? "",
-            filePath: chunk.filePath ?? void 0,
-            startOffset: match.startOffset,
-            endOffset: match.endOffset,
-            snippet: buildSnippet(
-              chunk.content ?? "",
-              match.startOffset,
-              match.endOffset,
-              contextChars
-            )
-          });
+          matches.push(toGrepMatch(indexed, match, contextChars));
           if (matches.length >= maxResults) {
             const continuationCursor = createGrepContinuationCursor({
               documentId,
@@ -3043,17 +3020,7 @@ var Knowledge = class _Knowledge {
     for (const chunk of scopedChunks) {
       scannedChunks += 1;
       for (const match of matcher(chunk.content)) {
-        matches.push({
-          position: chunk.position,
-          chunkId: chunk.chunkId,
-          chunkType: chunk.chunkType,
-          sectionPath: chunk.sectionPath,
-          sourceChunkPath: chunk.sourceChunkPath,
-          filePath: chunk.filePath,
-          startOffset: match.startOffset,
-          endOffset: match.endOffset,
-          snippet: buildSnippet(chunk.content, match.startOffset, match.endOffset, contextChars)
-        });
+        matches.push(toGrepMatch(chunk, match, contextChars));
         if (matches.length >= maxResults) {
           return {
             document: createStoredKnowledgeDocument({
@@ -4083,6 +4050,20 @@ function toReadChunk(chunk) {
     metadata: chunk.metadata
   };
 }
+function toGrepMatch(chunk, match, contextChars) {
+  return {
+    position: chunk.position,
+    chunkId: chunk.chunkId,
+    chunkType: chunk.chunkType,
+    sectionPath: chunk.sectionPath,
+    sourceChunkPath: chunk.sourceChunkPath,
+    filePath: chunk.filePath,
+    startOffset: match.startOffset,
+    endOffset: match.endOffset,
+    snippet: buildSnippet(chunk.content, match.startOffset, match.endOffset, contextChars),
+    ...chunk.pageNumbers && chunk.pageNumbers.length > 0 ? { pageNumbers: [...chunk.pageNumbers] } : {}
+  };
+}
 function matchesGrepScope(chunk, params) {
   if (params.chunkType && chunk.chunkType !== params.chunkType) {
     return false;

package/dist/index.mjs

@@ -2549,17 +2549,7 @@ var Knowledge = class _Knowledge {
       scannedChunks += 1;
       const chunkMatches = matcher(chunk.content);
       for (const match of chunkMatches) {
-        matches.push({
-          position: chunk.position,
-          chunkId: chunk.chunkId,
-          chunkType: chunk.chunkType,
-          sectionPath: chunk.sectionPath,
-          sourceChunkPath: chunk.sourceChunkPath,
-          filePath: chunk.filePath,
-          startOffset: match.startOffset,
-          endOffset: match.endOffset,
-          snippet: buildSnippet(chunk.content, match.startOffset, match.endOffset, contextChars)
-        });
+        matches.push(toGrepMatch(chunk, match, contextChars));
         if (matches.length >= maxResults) {
           return { document, matches, scannedChunks, truncated: true };
         }
@@ -2573,7 +2563,8 @@ var Knowledge = class _Knowledge {
       query: params.query,
       namespace: params.namespace,
       topK: params.topK,
-      useAgentic: params.useAgentic ?? false
+      // Omit when undefined so the API default (map-nav) applies; false → classic.
+      useAgentic: params.useAgentic
     });
     const documentByServerId = new Map(
       localDocuments.filter((document) => document.documentId).map((document) => [document.documentId, document])
@@ -2790,31 +2781,17 @@ var Knowledge = class _Knowledge {
         if (response.pagination.page === startPage && cursor?.nextChunkIndex !== void 0 && chunkIndex < cursor.nextChunkIndex) {
           continue;
         }
-        if (!matchesGrepScope(toIndexedRemoteChunk(chunk), params)) {
+        const indexed = toIndexedRemoteChunk(chunk);
+        if (!matchesGrepScope(indexed, params)) {
           continue;
         }
         scannedChunks += 1;
-        const chunkMatches = matcher(chunk.content ?? "");
+        const chunkMatches = matcher(indexed.content);
         for (const [matchIndex, match] of chunkMatches.entries()) {
           if (response.pagination.page === startPage && cursor?.nextChunkIndex === chunkIndex && cursor.nextMatchIndex !== void 0 && matchIndex < cursor.nextMatchIndex) {
             continue;
           }
-          matches.push({
-            position: toChunkPosition(chunk),
-            chunkId: chunk.chunkId,
-            chunkType: chunk.chunkType,
-            sectionPath: chunk.sectionPath ?? "",
-            sourceChunkPath: chunk.sourceChunkPath ?? chunk.sectionPath ?? "",
-            filePath: chunk.filePath ?? void 0,
-            startOffset: match.startOffset,
-            endOffset: match.endOffset,
-            snippet: buildSnippet(
-              chunk.content ?? "",
-              match.startOffset,
-              match.endOffset,
-              contextChars
-            )
-          });
+          matches.push(toGrepMatch(indexed, match, contextChars));
           if (matches.length >= maxResults) {
             const continuationCursor = createGrepContinuationCursor({
               documentId,
@@ -2978,17 +2955,7 @@ var Knowledge = class _Knowledge {
     for (const chunk of scopedChunks) {
       scannedChunks += 1;
       for (const match of matcher(chunk.content)) {
-        matches.push({
-          position: chunk.position,
-          chunkId: chunk.chunkId,
-          chunkType: chunk.chunkType,
-          sectionPath: chunk.sectionPath,
-          sourceChunkPath: chunk.sourceChunkPath,
-          filePath: chunk.filePath,
-          startOffset: match.startOffset,
-          endOffset: match.endOffset,
-          snippet: buildSnippet(chunk.content, match.startOffset, match.endOffset, contextChars)
-        });
+        matches.push(toGrepMatch(chunk, match, contextChars));
         if (matches.length >= maxResults) {
           return {
             document: createStoredKnowledgeDocument({
@@ -4018,6 +3985,20 @@ function toReadChunk(chunk) {
     metadata: chunk.metadata
   };
 }
+function toGrepMatch(chunk, match, contextChars) {
+  return {
+    position: chunk.position,
+    chunkId: chunk.chunkId,
+    chunkType: chunk.chunkType,
+    sectionPath: chunk.sectionPath,
+    sourceChunkPath: chunk.sourceChunkPath,
+    filePath: chunk.filePath,
+    startOffset: match.startOffset,
+    endOffset: match.endOffset,
+    snippet: buildSnippet(chunk.content, match.startOffset, match.endOffset, contextChars),
+    ...chunk.pageNumbers && chunk.pageNumbers.length > 0 ? { pageNumbers: [...chunk.pageNumbers] } : {}
+  };
+}
 function matchesGrepScope(chunk, params) {
   if (params.chunkType && chunk.chunkType !== params.chunkType) {
     return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontos-ai/knowhere-sdk",
-  "version": "2.2.0-beta.20260716073420",
+  "version": "2.3.0",
   "description": "Official Node.js SDK for Knowhere document parsing API",
   "keywords": [
     "knowhere",