@ontos-ai/knowhere-sdk 0.5.0 → 0.6.0

package/README.md

@@ -198,6 +198,9 @@ 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.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);
@@ -218,6 +221,20 @@ result.source.sourceFileName;
 result.source.sectionPath;
 ```
 
+Agentic references expose the current retrieval citation fields:
+
+```typescript
+const reference = response.referencedChunks[0];
+
+reference.chunkId;
+reference.documentId;
+reference.chunkType;
+reference.sectionPath;
+reference.filePath;
+reference.jobId;
+reference.assetUrl;
+```
+
 Use `documentId` to update or archive a document:
 
 ```typescript

package/dist/index.d.mts

@@ -679,11 +679,11 @@ interface RetrievalQueryParams {
  */
 interface RetrievalSource {
     /** Stable document identifier */
-    documentId?: string;
+    documentId?: string | null;
     /** Original source file name */
-    sourceFileName?: string;
+    sourceFileName?: string | null;
     /** Human-readable section path */
-    sectionPath?: string;
+    sectionPath?: string | null;
 }
 /**
  * Canonical chunk result returned by retrieval query.
@@ -693,15 +693,39 @@ interface RetrievalResult {
     content: string;
     /** Chunk type, for example text, image, or table */
     chunkType: string;
-    /** Retrieval score returned by the API */
-    score: number;
+    /** Retrieval score returned by the API. Null when no score is available (agentic navigation-only results). */
+    score: number | null;
     /** Presigned asset URL for media chunks when available */
     assetUrl?: string;
     /** Source reference for this result */
     source: RetrievalSource;
 }
+/**
+ * Cited evidence chunk returned by agentic retrieval.
+ */
+interface RetrievalReferencedChunk {
+    /** Parser-provided chunk identifier */
+    chunkId: string;
+    /** Stable document identifier */
+    documentId: string;
+    /** Chunk type, for example text, image, or table */
+    chunkType: string;
+    /** Human-readable section path */
+    sectionPath: string;
+    /** Generated artifact file path for media chunks */
+    filePath?: string | null;
+    /** Published job identifier for the referenced chunk */
+    jobId?: string | null;
+    /** Presigned asset URL for media chunks when available */
+    assetUrl?: string | null;
+}
 /**
  * Response from POST /v1/retrieval/query.
+ *
+ * Three PRIMARY output fields for downstream agent consumption:
+ * - `evidenceText`: hierarchical evidence tree for LLM context
+ * - `decisionTrace`: per-step navigation decisions (includes stop/failure)
+ * - `referencedChunks`: structured chunk citations for follow-up queries
  */
 interface RetrievalQueryResponse {
     /** Namespace searched by the API */
@@ -709,11 +733,19 @@ interface RetrievalQueryResponse {
     /** Echoed query text */
     query: string;
     /** Retrieval router path used by the API for this query */
-    routerUsed?: string;
-    /** LLM-generated natural-language answer (agentic mode only) */
-    answerText?: string | null;
-    /** Cited evidence chunks with asset URLs (agentic mode only) */
-    referencedChunks?: Array<Record<string, unknown>> | null;
+    routerUsed: string;
+    /** 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 */
+    evidenceText?: string | null;
+    /** Reason why the agentic run stopped (e.g. answer_done, not_found) */
+    stopReason?: string | null;
+    /** Semantic failure reason when the agentic evidence is insufficient */
+    failureReason?: string | null;
+    /** Per-step navigation decisions from agentic retrieval, including terminal stop/failure */
+    decisionTrace?: Record<string, unknown>[];
     /** Ranked retrieval results */
     results: RetrievalResult[];
 }
@@ -1056,4 +1088,4 @@ declare class JobFailedError extends KnowhereError {
     constructor(message: string, code: string, jobResult: JobResult);
 }
 
-export { APIError, AuthenticationError, BadRequestError, type BaseChunk, ChecksumError, type Chunk, ConflictError, type CreateJobParams, type DocType, type Document, type DocumentChunk, type DocumentChunkGetParams, type DocumentChunkListParams, type DocumentChunkListResponse, type DocumentChunkPagination, type DocumentChunkResponse, type DocumentChunkType, type DocumentListResponse, Documents, type FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, KnowhereError, type KnowhereOptions, type LoadOptions, type Manifest, NetworkError, NotFoundError, type ParseParams, type ParseResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, Retrieval, type RetrievalChannel, type RetrievalFilterMode, type RetrievalQueryParams, type RetrievalQueryResponse, 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 };
+export { APIError, AuthenticationError, BadRequestError, type BaseChunk, ChecksumError, type Chunk, ConflictError, type CreateJobParams, type DocType, type Document, type DocumentChunk, type DocumentChunkGetParams, type DocumentChunkListParams, type DocumentChunkListResponse, type DocumentChunkPagination, type DocumentChunkResponse, type DocumentChunkType, type DocumentListResponse, Documents, type FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, KnowhereError, type KnowhereOptions, type LoadOptions, type Manifest, NetworkError, NotFoundError, type ParseParams, type ParseResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, Retrieval, type RetrievalChannel, 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 };

package/dist/index.d.ts

@@ -679,11 +679,11 @@ interface RetrievalQueryParams {
  */
 interface RetrievalSource {
     /** Stable document identifier */
-    documentId?: string;
+    documentId?: string | null;
     /** Original source file name */
-    sourceFileName?: string;
+    sourceFileName?: string | null;
     /** Human-readable section path */
-    sectionPath?: string;
+    sectionPath?: string | null;
 }
 /**
  * Canonical chunk result returned by retrieval query.
@@ -693,15 +693,39 @@ interface RetrievalResult {
     content: string;
     /** Chunk type, for example text, image, or table */
     chunkType: string;
-    /** Retrieval score returned by the API */
-    score: number;
+    /** Retrieval score returned by the API. Null when no score is available (agentic navigation-only results). */
+    score: number | null;
     /** Presigned asset URL for media chunks when available */
     assetUrl?: string;
     /** Source reference for this result */
     source: RetrievalSource;
 }
+/**
+ * Cited evidence chunk returned by agentic retrieval.
+ */
+interface RetrievalReferencedChunk {
+    /** Parser-provided chunk identifier */
+    chunkId: string;
+    /** Stable document identifier */
+    documentId: string;
+    /** Chunk type, for example text, image, or table */
+    chunkType: string;
+    /** Human-readable section path */
+    sectionPath: string;
+    /** Generated artifact file path for media chunks */
+    filePath?: string | null;
+    /** Published job identifier for the referenced chunk */
+    jobId?: string | null;
+    /** Presigned asset URL for media chunks when available */
+    assetUrl?: string | null;
+}
 /**
  * Response from POST /v1/retrieval/query.
+ *
+ * Three PRIMARY output fields for downstream agent consumption:
+ * - `evidenceText`: hierarchical evidence tree for LLM context
+ * - `decisionTrace`: per-step navigation decisions (includes stop/failure)
+ * - `referencedChunks`: structured chunk citations for follow-up queries
  */
 interface RetrievalQueryResponse {
     /** Namespace searched by the API */
@@ -709,11 +733,19 @@ interface RetrievalQueryResponse {
     /** Echoed query text */
     query: string;
     /** Retrieval router path used by the API for this query */
-    routerUsed?: string;
-    /** LLM-generated natural-language answer (agentic mode only) */
-    answerText?: string | null;
-    /** Cited evidence chunks with asset URLs (agentic mode only) */
-    referencedChunks?: Array<Record<string, unknown>> | null;
+    routerUsed: string;
+    /** 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 */
+    evidenceText?: string | null;
+    /** Reason why the agentic run stopped (e.g. answer_done, not_found) */
+    stopReason?: string | null;
+    /** Semantic failure reason when the agentic evidence is insufficient */
+    failureReason?: string | null;
+    /** Per-step navigation decisions from agentic retrieval, including terminal stop/failure */
+    decisionTrace?: Record<string, unknown>[];
     /** Ranked retrieval results */
     results: RetrievalResult[];
 }
@@ -1056,4 +1088,4 @@ declare class JobFailedError extends KnowhereError {
     constructor(message: string, code: string, jobResult: JobResult);
 }
 
-export { APIError, AuthenticationError, BadRequestError, type BaseChunk, ChecksumError, type Chunk, ConflictError, type CreateJobParams, type DocType, type Document, type DocumentChunk, type DocumentChunkGetParams, type DocumentChunkListParams, type DocumentChunkListResponse, type DocumentChunkPagination, type DocumentChunkResponse, type DocumentChunkType, type DocumentListResponse, Documents, type FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, KnowhereError, type KnowhereOptions, type LoadOptions, type Manifest, NetworkError, NotFoundError, type ParseParams, type ParseResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, Retrieval, type RetrievalChannel, type RetrievalFilterMode, type RetrievalQueryParams, type RetrievalQueryResponse, 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 };
+export { APIError, AuthenticationError, BadRequestError, type BaseChunk, ChecksumError, type Chunk, ConflictError, type CreateJobParams, type DocType, type Document, type DocumentChunk, type DocumentChunkGetParams, type DocumentChunkListParams, type DocumentChunkListResponse, type DocumentChunkPagination, type DocumentChunkResponse, type DocumentChunkType, type DocumentListResponse, Documents, type FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, KnowhereError, type KnowhereOptions, type LoadOptions, type Manifest, NetworkError, NotFoundError, type ParseParams, type ParseResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, Retrieval, type RetrievalChannel, 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 };

package/package.json

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