@ontos-ai/knowhere-sdk 2.2.0 → 2.4.0

package/README.md

@@ -311,12 +311,13 @@ const response = await client.retrieval.query({
 
 console.log(response.answerText); // LLM-generated answer
 console.log(response.referencedChunks); // cited evidence chunks
-console.log(response.evidenceText); // rendered evidence context, when returned
+console.log(response.evidence); // composed parts to consume (text/HTML and inline images)
+console.log(response.evidenceText); // text projection of those parts
 console.log(response.stopReason); // agentic termination reason, when returned
 console.log(response.failureReason); // no-answer reason, when returned
 
 for (const result of response.results) {
-  console.log(result.content);
+  console.log(result.content); // raw path chunk for debug
   console.log(result.contentSource);
   console.log(result.score);
   console.log(result.metadata?.pageNums);
@@ -515,12 +516,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[];
@@ -877,13 +883,24 @@ interface RetrievalSource {
     /** Human-readable section path */
     sectionPath?: string | null;
 }
+/**
+ * One composed evidence part. Tables stay in text as HTML; images are inline bytes.
+ */
+type RetrievalEvidencePart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    mediaType: string;
+    data: string;
+};
 /**
  * Canonical chunk result returned by retrieval query.
  */
 interface RetrievalResult {
     /** Parser-provided chunk identifier when included by the API */
     chunkId?: string;
-    /** Knowledge content to use directly in the caller's answer */
+    /** Raw chunk body for debug. Placeholders stay intact. */
     content: string;
     /** Chunk type, for example text, image, table, or page */
     chunkType: string;
@@ -930,8 +947,10 @@ interface RetrievalReferencedChunk {
 /**
  * Response from POST /v2/retrieval/query.
  *
- * Three PRIMARY output fields for downstream agent consumption:
- * - `evidenceText`: hierarchical evidence tree for LLM context
+ * Downstream agents consume:
+ * - `evidence`: composed parts (text/HTML and inline images)
+ * - `evidenceText`: text projection of those parts
+ * - `results`: raw path chunks for debug
  * - `decisionTrace`: per-step navigation decisions (includes stop/failure)
  * - `referencedChunks`: structured chunk citations for follow-up queries
  */
@@ -942,11 +961,13 @@ interface RetrievalQueryResponse {
     query: string;
     /** Retrieval router path used by the API for this query */
     routerUsed: string;
+    /** Composed evidence parts in result order */
+    evidence?: RetrievalEvidencePart[];
     /** LLM-generated natural-language answer, or null when no answer was produced */
     answerText: string | null;
     /** Cited evidence chunks with asset URLs when available */
     referencedChunks: RetrievalReferencedChunk[];
-    /** Tree-structured evidence text rendered by the agentic navigator */
+    /** Text projection of evidence. Tables stay as HTML; images are data URLs. */
     evidenceText?: string | null;
     /** Reason why the agentic run stopped (e.g. answer_done, not_found) */
     stopReason?: string | null;
@@ -1383,6 +1404,7 @@ interface KnowledgeSearchReference {
 interface KnowledgeSearchResponse {
     namespace?: string;
     query: string;
+    evidence?: RetrievalEvidencePart[];
     evidenceText?: string | null;
     references: KnowledgeSearchReference[];
     results: KnowledgeSearchResult[];
@@ -1722,4 +1744,4 @@ declare class JobFailedError extends KnowhereError {
     constructor(message: string, code: string, jobResult: JobResult);
 }
 
-export { APIError, type AuthTokenProvider, AuthenticationError, BadRequestError, type BaseChunk, ChecksumError, type Chunk, ConflictError, type CreateJobParams, DiskParsedDocumentStorage, type DocType, type Document, type DocumentChunk, type DocumentChunkGetParams, type DocumentChunkListParams, type DocumentChunkListResponse, type DocumentChunkPagination, type DocumentChunkResponse, type DocumentChunkType, type DocumentListPagination, type DocumentListParams, type DocumentListResponse, type DocumentMetadata, type DocumentPageCitationSource, Documents, type FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, type KnowhereAssetStorageAdapter, type KnowhereAssetStorageBody, type KnowhereAssetStorageHead, type KnowhereAssetStorageObject, type KnowhereAssetStorageOptions, type KnowhereAssetStorageResult, type KnowhereAssetStorageWriteResult, KnowhereError, type KnowhereOptions, Knowledge, type KnowledgeAsyncJobStatusResponse, type KnowledgeAsyncParseParams, type KnowledgeAsyncParseResponse, type KnowledgeCacheDocumentParams, type KnowledgeCacheJobResultParams, type KnowledgeChunkType, type KnowledgeDocumentReference, type KnowledgeGrepMatch, type KnowledgeGrepParams, type KnowledgeGrepResponse, type KnowledgeImportJobResultParams, type KnowledgeJobResultResponse, type KnowledgeLoadJobResultParams, type KnowledgeOutline, type KnowledgeParseParams, type KnowledgeParsedStorageOptions, type KnowledgeReadChunk, type KnowledgeReadParams, type KnowledgeReadResponse, type KnowledgeSearchParams, type KnowledgeSearchReference, type KnowledgeSearchResponse, type KnowledgeSearchResult, type KnowledgeSection, type KnowledgeStartupRecoveryResponse, type KnowledgeSyncParsedDocumentParams, type KnowledgeSyncParsedDocumentResponse, type LlmConfig, type LlmModelsConfig, type LlmProviderConfig, type LoadOptions, type LocalKnowledgeDocument, type LocalKnowledgeParseResponse, LocalKnowledgeStore, type Manifest, NODE_SDK_DOCUMENT_METADATA_DEFAULTS, NetworkError, NotFoundError, type PageChunk, type PageCitationAsset, type PageCitationAssetContentType, type PageCitationAssetSource, type ParseParams, type ParseResult, type ParsedDocumentCommit, type ParsedDocumentCommitSource, type ParsedDocumentObject, type ParsedDocumentObjectHead, type ParsedDocumentObjectParams, type ParsedDocumentRevisionParams, type ParsedDocumentStorage, type ParsedDocumentStorageConfig, type ParsedDocumentStorageDocument, type ParsedDocumentStorageLimits, type ParsedDocumentSyncProgress, type ParsedDocumentSyncScheduler, type ParsedDocumentWriteObjectParams, type ParsedDocumentWriteObjectResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, Retrieval, type RetrievalChannel, type RetrievalChunkType, type RetrievalFilterMode, type RetrievalQueryParams, type RetrievalQueryResponse, type RetrievalReferencedChunk, type RetrievalResult, type RetrievalSectionExclusion, type RetrievalSource, ServiceUnavailableError, type Statistics, type TableChunk, type TextChunk, TimeoutError, type UploadParams, type UploadProgress, VERSION, ValidationError, type WaitOptions, type WebhookConfig, Knowhere as default, mergeDocumentMetadataDefaults, storeParseResultAssets, syncParseResultToParsedDocumentStorage };
+export { APIError, type AuthTokenProvider, AuthenticationError, BadRequestError, type BaseChunk, ChecksumError, type Chunk, ConflictError, type CreateJobParams, DiskParsedDocumentStorage, type DocType, type Document, type DocumentChunk, type DocumentChunkGetParams, type DocumentChunkListParams, type DocumentChunkListResponse, type DocumentChunkPagination, type DocumentChunkResponse, type DocumentChunkType, type DocumentListPagination, type DocumentListParams, type DocumentListResponse, type DocumentMetadata, type DocumentPageCitationSource, Documents, type FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, type KnowhereAssetStorageAdapter, type KnowhereAssetStorageBody, type KnowhereAssetStorageHead, type KnowhereAssetStorageObject, type KnowhereAssetStorageOptions, type KnowhereAssetStorageResult, type KnowhereAssetStorageWriteResult, KnowhereError, type KnowhereOptions, Knowledge, type KnowledgeAsyncJobStatusResponse, type KnowledgeAsyncParseParams, type KnowledgeAsyncParseResponse, type KnowledgeCacheDocumentParams, type KnowledgeCacheJobResultParams, type KnowledgeChunkType, type KnowledgeDocumentReference, type KnowledgeGrepMatch, type KnowledgeGrepParams, type KnowledgeGrepResponse, type KnowledgeImportJobResultParams, type KnowledgeJobResultResponse, type KnowledgeLoadJobResultParams, type KnowledgeOutline, type KnowledgeParseParams, type KnowledgeParsedStorageOptions, type KnowledgeReadChunk, type KnowledgeReadParams, type KnowledgeReadResponse, type KnowledgeSearchParams, type KnowledgeSearchReference, type KnowledgeSearchResponse, type KnowledgeSearchResult, type KnowledgeSection, type KnowledgeStartupRecoveryResponse, type KnowledgeSyncParsedDocumentParams, type KnowledgeSyncParsedDocumentResponse, type LlmConfig, type LlmModelsConfig, type LlmProviderConfig, type LoadOptions, type LocalKnowledgeDocument, type LocalKnowledgeParseResponse, LocalKnowledgeStore, type Manifest, NODE_SDK_DOCUMENT_METADATA_DEFAULTS, NetworkError, NotFoundError, type PageChunk, type PageCitationAsset, type PageCitationAssetContentType, type PageCitationAssetSource, type ParseParams, type ParseResult, type ParsedDocumentCommit, type ParsedDocumentCommitSource, type ParsedDocumentObject, type ParsedDocumentObjectHead, type ParsedDocumentObjectParams, type ParsedDocumentRevisionParams, type ParsedDocumentStorage, type ParsedDocumentStorageConfig, type ParsedDocumentStorageDocument, type ParsedDocumentStorageLimits, type ParsedDocumentSyncProgress, type ParsedDocumentSyncScheduler, type ParsedDocumentWriteObjectParams, type ParsedDocumentWriteObjectResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, Retrieval, type RetrievalChannel, type RetrievalChunkType, type RetrievalEvidencePart, type RetrievalFilterMode, type RetrievalQueryParams, type RetrievalQueryResponse, type RetrievalReferencedChunk, type RetrievalResult, type RetrievalSectionExclusion, type RetrievalSource, ServiceUnavailableError, type Statistics, type TableChunk, type TextChunk, TimeoutError, type UploadParams, type UploadProgress, VERSION, ValidationError, type WaitOptions, type WebhookConfig, Knowhere as default, mergeDocumentMetadataDefaults, storeParseResultAssets, syncParseResultToParsedDocumentStorage };

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[];
@@ -877,13 +883,24 @@ interface RetrievalSource {
     /** Human-readable section path */
     sectionPath?: string | null;
 }
+/**
+ * One composed evidence part. Tables stay in text as HTML; images are inline bytes.
+ */
+type RetrievalEvidencePart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    mediaType: string;
+    data: string;
+};
 /**
  * Canonical chunk result returned by retrieval query.
  */
 interface RetrievalResult {
     /** Parser-provided chunk identifier when included by the API */
     chunkId?: string;
-    /** Knowledge content to use directly in the caller's answer */
+    /** Raw chunk body for debug. Placeholders stay intact. */
     content: string;
     /** Chunk type, for example text, image, table, or page */
     chunkType: string;
@@ -930,8 +947,10 @@ interface RetrievalReferencedChunk {
 /**
  * Response from POST /v2/retrieval/query.
  *
- * Three PRIMARY output fields for downstream agent consumption:
- * - `evidenceText`: hierarchical evidence tree for LLM context
+ * Downstream agents consume:
+ * - `evidence`: composed parts (text/HTML and inline images)
+ * - `evidenceText`: text projection of those parts
+ * - `results`: raw path chunks for debug
  * - `decisionTrace`: per-step navigation decisions (includes stop/failure)
  * - `referencedChunks`: structured chunk citations for follow-up queries
  */
@@ -942,11 +961,13 @@ interface RetrievalQueryResponse {
     query: string;
     /** Retrieval router path used by the API for this query */
     routerUsed: string;
+    /** Composed evidence parts in result order */
+    evidence?: RetrievalEvidencePart[];
     /** LLM-generated natural-language answer, or null when no answer was produced */
     answerText: string | null;
     /** Cited evidence chunks with asset URLs when available */
     referencedChunks: RetrievalReferencedChunk[];
-    /** Tree-structured evidence text rendered by the agentic navigator */
+    /** Text projection of evidence. Tables stay as HTML; images are data URLs. */
     evidenceText?: string | null;
     /** Reason why the agentic run stopped (e.g. answer_done, not_found) */
     stopReason?: string | null;
@@ -1383,6 +1404,7 @@ interface KnowledgeSearchReference {
 interface KnowledgeSearchResponse {
     namespace?: string;
     query: string;
+    evidence?: RetrievalEvidencePart[];
     evidenceText?: string | null;
     references: KnowledgeSearchReference[];
     results: KnowledgeSearchResult[];
@@ -1722,4 +1744,4 @@ declare class JobFailedError extends KnowhereError {
     constructor(message: string, code: string, jobResult: JobResult);
 }
 
-export { APIError, type AuthTokenProvider, AuthenticationError, BadRequestError, type BaseChunk, ChecksumError, type Chunk, ConflictError, type CreateJobParams, DiskParsedDocumentStorage, type DocType, type Document, type DocumentChunk, type DocumentChunkGetParams, type DocumentChunkListParams, type DocumentChunkListResponse, type DocumentChunkPagination, type DocumentChunkResponse, type DocumentChunkType, type DocumentListPagination, type DocumentListParams, type DocumentListResponse, type DocumentMetadata, type DocumentPageCitationSource, Documents, type FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, type KnowhereAssetStorageAdapter, type KnowhereAssetStorageBody, type KnowhereAssetStorageHead, type KnowhereAssetStorageObject, type KnowhereAssetStorageOptions, type KnowhereAssetStorageResult, type KnowhereAssetStorageWriteResult, KnowhereError, type KnowhereOptions, Knowledge, type KnowledgeAsyncJobStatusResponse, type KnowledgeAsyncParseParams, type KnowledgeAsyncParseResponse, type KnowledgeCacheDocumentParams, type KnowledgeCacheJobResultParams, type KnowledgeChunkType, type KnowledgeDocumentReference, type KnowledgeGrepMatch, type KnowledgeGrepParams, type KnowledgeGrepResponse, type KnowledgeImportJobResultParams, type KnowledgeJobResultResponse, type KnowledgeLoadJobResultParams, type KnowledgeOutline, type KnowledgeParseParams, type KnowledgeParsedStorageOptions, type KnowledgeReadChunk, type KnowledgeReadParams, type KnowledgeReadResponse, type KnowledgeSearchParams, type KnowledgeSearchReference, type KnowledgeSearchResponse, type KnowledgeSearchResult, type KnowledgeSection, type KnowledgeStartupRecoveryResponse, type KnowledgeSyncParsedDocumentParams, type KnowledgeSyncParsedDocumentResponse, type LlmConfig, type LlmModelsConfig, type LlmProviderConfig, type LoadOptions, type LocalKnowledgeDocument, type LocalKnowledgeParseResponse, LocalKnowledgeStore, type Manifest, NODE_SDK_DOCUMENT_METADATA_DEFAULTS, NetworkError, NotFoundError, type PageChunk, type PageCitationAsset, type PageCitationAssetContentType, type PageCitationAssetSource, type ParseParams, type ParseResult, type ParsedDocumentCommit, type ParsedDocumentCommitSource, type ParsedDocumentObject, type ParsedDocumentObjectHead, type ParsedDocumentObjectParams, type ParsedDocumentRevisionParams, type ParsedDocumentStorage, type ParsedDocumentStorageConfig, type ParsedDocumentStorageDocument, type ParsedDocumentStorageLimits, type ParsedDocumentSyncProgress, type ParsedDocumentSyncScheduler, type ParsedDocumentWriteObjectParams, type ParsedDocumentWriteObjectResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, Retrieval, type RetrievalChannel, type RetrievalChunkType, type RetrievalFilterMode, type RetrievalQueryParams, type RetrievalQueryResponse, type RetrievalReferencedChunk, type RetrievalResult, type RetrievalSectionExclusion, type RetrievalSource, ServiceUnavailableError, type Statistics, type TableChunk, type TextChunk, TimeoutError, type UploadParams, type UploadProgress, VERSION, ValidationError, type WaitOptions, type WebhookConfig, Knowhere as default, mergeDocumentMetadataDefaults, storeParseResultAssets, syncParseResultToParsedDocumentStorage };
+export { APIError, type AuthTokenProvider, AuthenticationError, BadRequestError, type BaseChunk, ChecksumError, type Chunk, ConflictError, type CreateJobParams, DiskParsedDocumentStorage, type DocType, type Document, type DocumentChunk, type DocumentChunkGetParams, type DocumentChunkListParams, type DocumentChunkListResponse, type DocumentChunkPagination, type DocumentChunkResponse, type DocumentChunkType, type DocumentListPagination, type DocumentListParams, type DocumentListResponse, type DocumentMetadata, type DocumentPageCitationSource, Documents, type FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, type KnowhereAssetStorageAdapter, type KnowhereAssetStorageBody, type KnowhereAssetStorageHead, type KnowhereAssetStorageObject, type KnowhereAssetStorageOptions, type KnowhereAssetStorageResult, type KnowhereAssetStorageWriteResult, KnowhereError, type KnowhereOptions, Knowledge, type KnowledgeAsyncJobStatusResponse, type KnowledgeAsyncParseParams, type KnowledgeAsyncParseResponse, type KnowledgeCacheDocumentParams, type KnowledgeCacheJobResultParams, type KnowledgeChunkType, type KnowledgeDocumentReference, type KnowledgeGrepMatch, type KnowledgeGrepParams, type KnowledgeGrepResponse, type KnowledgeImportJobResultParams, type KnowledgeJobResultResponse, type KnowledgeLoadJobResultParams, type KnowledgeOutline, type KnowledgeParseParams, type KnowledgeParsedStorageOptions, type KnowledgeReadChunk, type KnowledgeReadParams, type KnowledgeReadResponse, type KnowledgeSearchParams, type KnowledgeSearchReference, type KnowledgeSearchResponse, type KnowledgeSearchResult, type KnowledgeSection, type KnowledgeStartupRecoveryResponse, type KnowledgeSyncParsedDocumentParams, type KnowledgeSyncParsedDocumentResponse, type LlmConfig, type LlmModelsConfig, type LlmProviderConfig, type LoadOptions, type LocalKnowledgeDocument, type LocalKnowledgeParseResponse, LocalKnowledgeStore, type Manifest, NODE_SDK_DOCUMENT_METADATA_DEFAULTS, NetworkError, NotFoundError, type PageChunk, type PageCitationAsset, type PageCitationAssetContentType, type PageCitationAssetSource, type ParseParams, type ParseResult, type ParsedDocumentCommit, type ParsedDocumentCommitSource, type ParsedDocumentObject, type ParsedDocumentObjectHead, type ParsedDocumentObjectParams, type ParsedDocumentRevisionParams, type ParsedDocumentStorage, type ParsedDocumentStorageConfig, type ParsedDocumentStorageDocument, type ParsedDocumentStorageLimits, type ParsedDocumentSyncProgress, type ParsedDocumentSyncScheduler, type ParsedDocumentWriteObjectParams, type ParsedDocumentWriteObjectResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, Retrieval, type RetrievalChannel, type RetrievalChunkType, type RetrievalEvidencePart, type RetrievalFilterMode, type RetrievalQueryParams, type RetrievalQueryResponse, type RetrievalReferencedChunk, type RetrievalResult, type RetrievalSectionExclusion, type RetrievalSource, ServiceUnavailableError, type Statistics, type TableChunk, type TextChunk, TimeoutError, type UploadParams, type UploadProgress, VERSION, ValidationError, type WaitOptions, type WebhookConfig, Knowhere as default, mergeDocumentMetadataDefaults, storeParseResultAssets, syncParseResultToParsedDocumentStorage };

package/dist/index.js

@@ -2637,6 +2637,7 @@ var Knowledge = class _Knowledge {
     return {
       namespace: rawResponse.namespace,
       query: rawResponse.query,
+      evidence: rawResponse.evidence ?? [],
       evidenceText: rawResponse.evidenceText,
       references: [
         ...rawResponse.referencedChunks.map(

package/dist/index.mjs

@@ -2572,6 +2572,7 @@ var Knowledge = class _Knowledge {
     return {
       namespace: rawResponse.namespace,
       query: rawResponse.query,
+      evidence: rawResponse.evidence ?? [],
       evidenceText: rawResponse.evidenceText,
       references: [
         ...rawResponse.referencedChunks.map(

package/package.json

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