@ontos-ai/knowhere-sdk 0.4.0 → 0.6.0

package/README.md

@@ -47,11 +47,11 @@ console.log(`Found ${result.textChunks.length} text chunks`);
 console.log(`Found ${result.imageChunks.length} images`);
 console.log(`Found ${result.tableChunks.length} tables`);
 
-// Work with chunks
+// Work with chunks — worker metadata is in chunk.metadata
 result.textChunks.forEach((chunk) => {
   console.log(chunk.content);
-  console.log(chunk.keywords);
-  console.log(chunk.summary);
+  console.log(chunk.metadata.keywords);
+  console.log(chunk.metadata.summary);
 });
 
 // Save results to disk
@@ -188,12 +188,20 @@ if (!documentId) {
 
 console.log(documentId);
 
+// Agentic mode (LLM navigation + answer synthesis)
 const response = await client.retrieval.query({
   namespace: 'support-center',
   query: 'How do I reset Bluetooth pairing?',
   topK: 5,
+  useAgentic: true,
 });
 
+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);
   console.log(result.score);
@@ -213,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

@@ -332,7 +332,6 @@ interface Manifest {
     dataId?: string;
     /** Original source file name */
     sourceFileName: string;
-    /** Processing completion date */
     /** Processing completion date (optional: only present if emitted by the worker) */
     processingDate?: Date;
     /** Worker-side processing metadata emitted by manifest v2 */
@@ -341,6 +340,13 @@ interface Manifest {
     statistics: Statistics;
     /** Legacy file index from earlier ZIP manifests */
     files?: FileIndex;
+    /**
+     * Document hierarchy emitted by the current worker.
+     *
+     * The key remains all-caps at runtime because ``keysToCamel()`` only
+     * transforms snake_case keys.
+     */
+    HIERARCHY?: Record<string, unknown>;
 }
 /**
  * Chunk relationship entry (metadata.connect_to per schema v2.1)
@@ -357,6 +363,58 @@ interface ConnectTo {
     /** Shared keywords (related only) */
     keywords?: string[];
 }
+/**
+ * A single image or table resource entry in ``doc_nav.json``.
+ */
+interface DocNavResourceItem {
+    path: string;
+    summary?: string;
+}
+/**
+ * Image and table resource summaries from ``doc_nav.json``.
+ */
+interface DocNavResources {
+    images: DocNavResourceItem[];
+    tables: DocNavResourceItem[];
+}
+/**
+ * A document section in the ``doc_nav.json`` navigation tree.
+ */
+interface DocNavSection {
+    title: string;
+    path: string;
+    level: number;
+    summary?: string;
+    chunkCount: number;
+    children: DocNavSection[];
+}
+/**
+ * Top-level document navigation structure from ``doc_nav.json``.
+ */
+interface DocNav {
+    sections: DocNavSection[];
+    resources?: DocNavResources;
+}
+/**
+ * Known worker metadata fields for a chunk.
+ *
+ * All fields are optional.  Unknown fields added by future worker
+ * versions are accessible through the index signature.
+ */
+interface ChunkMetadata {
+    length?: number;
+    pageNums?: number[];
+    tokens?: string[];
+    keywords?: string[];
+    summary?: string;
+    connectTo?: ConnectTo[];
+    filePath?: string;
+    originalName?: string;
+    tableType?: string;
+    documentTopSummary?: string;
+    /** Allow forward-compatible access to unknown fields. */
+    [key: string]: unknown;
+}
 /**
  * Base chunk properties
  */
@@ -369,50 +427,30 @@ interface BaseChunk {
     content: string;
     /** Relative path in ZIP */
     path: string;
-    /** Page numbers spanned by this chunk when provided by the backend */
-    pageNums?: number[];
+    /** Worker metadata for this chunk */
+    metadata: ChunkMetadata;
 }
 /**
- * Minimal chunk representation emitted in chunks_slim.json
+ * Minimal chunk representation emitted in chunks_slim.json (legacy).
  */
 interface SlimChunk {
     type: 'text' | 'image' | 'table';
     path: string;
     content: string;
-    summary?: string;
 }
 /**
  * Text chunk
  */
 interface TextChunk extends BaseChunk {
     type: 'text';
-    /** Content length */
-    length: number;
-    /** Extracted tokens from the current backend payload */
-    tokens?: string[];
-    /** Extracted keywords */
-    keywords?: string[];
-    /** Generated summary */
-    summary?: string;
-    /** Chunk relationships (schema v2.1: metadata.connect_to) */
-    connectTo?: ConnectTo[];
-    /**
-     * @deprecated Use connectTo instead. Retained for backward compatibility.
-     * Previously populated from metadata.relationships which is no longer emitted by the API.
-     */
-    relationships?: string[];
 }
 /**
  * Image chunk
  */
 interface ImageChunk extends BaseChunk {
     type: 'image';
-    /** Content length */
-    length: number;
     /** Relative file path in ZIP */
     filePath: string;
-    /** Generated summary */
-    summary?: string;
     /** Image data buffer */
     data: Buffer;
     /** Image format (derived from file extension) */
@@ -425,14 +463,8 @@ interface ImageChunk extends BaseChunk {
  */
 interface TableChunk extends BaseChunk {
     type: 'table';
-    /** Content length */
-    length: number;
     /** Relative file path in ZIP */
     filePath: string;
-    /** Table type */
-    tableType?: string;
-    /** Generated summary */
-    summary?: string;
     /** HTML representation */
     html: string;
     /** Save table HTML to disk */
@@ -450,20 +482,22 @@ interface ParseResult {
     manifest: Manifest;
     /** All chunks */
     chunks: Chunk[];
-    /** Minimal chunk projection from chunks_slim.json (if available) */
-    chunksSlim?: SlimChunk[];
+    /** Document navigation tree from doc_nav.json (current worker output) */
+    docNav?: DocNav;
     /** Full document as Markdown (if available) */
     fullMarkdown?: string;
-    /** Document hierarchy (if available) */
+    /** Raw ZIP buffer */
+    rawZip: Buffer;
+    /** @deprecated Current worker no longer emits chunks_slim.json */
+    chunksSlim?: SlimChunk[];
+    /** @deprecated Current worker no longer emits hierarchy.json */
     hierarchy?: unknown;
-    /** Table-of-contents hierarchy hints (if available) */
+    /** @deprecated Table-of-contents hierarchy hints (if available) */
     tocHierarchies?: unknown;
-    /** Knowledge-base CSV export (if available) */
+    /** @deprecated Knowledge-base CSV export (if available) */
     kbCsv?: string;
-    /** Pre-rendered hierarchy HTML view (if available) */
+    /** @deprecated Pre-rendered hierarchy HTML view (if available) */
     hierarchyViewHtml?: string;
-    /** Raw ZIP buffer */
-    rawZip: Buffer;
     /** Text chunks only */
     readonly textChunks: TextChunk[];
     /** Image chunks only */
@@ -611,6 +645,14 @@ interface RetrievalQueryParams {
     namespace?: string;
     /** Maximum number of results to return */
     topK?: number;
+    /**
+     * Force retrieval mode.
+     *
+     * - ``true``  — agentic (LLM navigation + answer synthesis)
+     * - ``false`` — legacy 3-channel RRF only
+     * - ``undefined`` / omitted — server default
+     */
+    useAgentic?: boolean;
     /** Chunk type filter: 1=all, 2=text, 3=image, 4=table, 5=text+image, 6=text+table */
     dataType?: 1 | 2 | 3 | 4 | 5 | 6;
     /** Path keywords for include/exclude filtering */
@@ -637,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.
@@ -651,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 */
@@ -667,7 +733,19 @@ interface RetrievalQueryResponse {
     /** Echoed query text */
     query: string;
     /** Retrieval router path used by the API for this query */
-    routerUsed?: string;
+    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[];
 }
@@ -1010,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

@@ -332,7 +332,6 @@ interface Manifest {
     dataId?: string;
     /** Original source file name */
     sourceFileName: string;
-    /** Processing completion date */
     /** Processing completion date (optional: only present if emitted by the worker) */
     processingDate?: Date;
     /** Worker-side processing metadata emitted by manifest v2 */
@@ -341,6 +340,13 @@ interface Manifest {
     statistics: Statistics;
     /** Legacy file index from earlier ZIP manifests */
     files?: FileIndex;
+    /**
+     * Document hierarchy emitted by the current worker.
+     *
+     * The key remains all-caps at runtime because ``keysToCamel()`` only
+     * transforms snake_case keys.
+     */
+    HIERARCHY?: Record<string, unknown>;
 }
 /**
  * Chunk relationship entry (metadata.connect_to per schema v2.1)
@@ -357,6 +363,58 @@ interface ConnectTo {
     /** Shared keywords (related only) */
     keywords?: string[];
 }
+/**
+ * A single image or table resource entry in ``doc_nav.json``.
+ */
+interface DocNavResourceItem {
+    path: string;
+    summary?: string;
+}
+/**
+ * Image and table resource summaries from ``doc_nav.json``.
+ */
+interface DocNavResources {
+    images: DocNavResourceItem[];
+    tables: DocNavResourceItem[];
+}
+/**
+ * A document section in the ``doc_nav.json`` navigation tree.
+ */
+interface DocNavSection {
+    title: string;
+    path: string;
+    level: number;
+    summary?: string;
+    chunkCount: number;
+    children: DocNavSection[];
+}
+/**
+ * Top-level document navigation structure from ``doc_nav.json``.
+ */
+interface DocNav {
+    sections: DocNavSection[];
+    resources?: DocNavResources;
+}
+/**
+ * Known worker metadata fields for a chunk.
+ *
+ * All fields are optional.  Unknown fields added by future worker
+ * versions are accessible through the index signature.
+ */
+interface ChunkMetadata {
+    length?: number;
+    pageNums?: number[];
+    tokens?: string[];
+    keywords?: string[];
+    summary?: string;
+    connectTo?: ConnectTo[];
+    filePath?: string;
+    originalName?: string;
+    tableType?: string;
+    documentTopSummary?: string;
+    /** Allow forward-compatible access to unknown fields. */
+    [key: string]: unknown;
+}
 /**
  * Base chunk properties
  */
@@ -369,50 +427,30 @@ interface BaseChunk {
     content: string;
     /** Relative path in ZIP */
     path: string;
-    /** Page numbers spanned by this chunk when provided by the backend */
-    pageNums?: number[];
+    /** Worker metadata for this chunk */
+    metadata: ChunkMetadata;
 }
 /**
- * Minimal chunk representation emitted in chunks_slim.json
+ * Minimal chunk representation emitted in chunks_slim.json (legacy).
  */
 interface SlimChunk {
     type: 'text' | 'image' | 'table';
     path: string;
     content: string;
-    summary?: string;
 }
 /**
  * Text chunk
  */
 interface TextChunk extends BaseChunk {
     type: 'text';
-    /** Content length */
-    length: number;
-    /** Extracted tokens from the current backend payload */
-    tokens?: string[];
-    /** Extracted keywords */
-    keywords?: string[];
-    /** Generated summary */
-    summary?: string;
-    /** Chunk relationships (schema v2.1: metadata.connect_to) */
-    connectTo?: ConnectTo[];
-    /**
-     * @deprecated Use connectTo instead. Retained for backward compatibility.
-     * Previously populated from metadata.relationships which is no longer emitted by the API.
-     */
-    relationships?: string[];
 }
 /**
  * Image chunk
  */
 interface ImageChunk extends BaseChunk {
     type: 'image';
-    /** Content length */
-    length: number;
     /** Relative file path in ZIP */
     filePath: string;
-    /** Generated summary */
-    summary?: string;
     /** Image data buffer */
     data: Buffer;
     /** Image format (derived from file extension) */
@@ -425,14 +463,8 @@ interface ImageChunk extends BaseChunk {
  */
 interface TableChunk extends BaseChunk {
     type: 'table';
-    /** Content length */
-    length: number;
     /** Relative file path in ZIP */
     filePath: string;
-    /** Table type */
-    tableType?: string;
-    /** Generated summary */
-    summary?: string;
     /** HTML representation */
     html: string;
     /** Save table HTML to disk */
@@ -450,20 +482,22 @@ interface ParseResult {
     manifest: Manifest;
     /** All chunks */
     chunks: Chunk[];
-    /** Minimal chunk projection from chunks_slim.json (if available) */
-    chunksSlim?: SlimChunk[];
+    /** Document navigation tree from doc_nav.json (current worker output) */
+    docNav?: DocNav;
     /** Full document as Markdown (if available) */
     fullMarkdown?: string;
-    /** Document hierarchy (if available) */
+    /** Raw ZIP buffer */
+    rawZip: Buffer;
+    /** @deprecated Current worker no longer emits chunks_slim.json */
+    chunksSlim?: SlimChunk[];
+    /** @deprecated Current worker no longer emits hierarchy.json */
     hierarchy?: unknown;
-    /** Table-of-contents hierarchy hints (if available) */
+    /** @deprecated Table-of-contents hierarchy hints (if available) */
     tocHierarchies?: unknown;
-    /** Knowledge-base CSV export (if available) */
+    /** @deprecated Knowledge-base CSV export (if available) */
     kbCsv?: string;
-    /** Pre-rendered hierarchy HTML view (if available) */
+    /** @deprecated Pre-rendered hierarchy HTML view (if available) */
     hierarchyViewHtml?: string;
-    /** Raw ZIP buffer */
-    rawZip: Buffer;
     /** Text chunks only */
     readonly textChunks: TextChunk[];
     /** Image chunks only */
@@ -611,6 +645,14 @@ interface RetrievalQueryParams {
     namespace?: string;
     /** Maximum number of results to return */
     topK?: number;
+    /**
+     * Force retrieval mode.
+     *
+     * - ``true``  — agentic (LLM navigation + answer synthesis)
+     * - ``false`` — legacy 3-channel RRF only
+     * - ``undefined`` / omitted — server default
+     */
+    useAgentic?: boolean;
     /** Chunk type filter: 1=all, 2=text, 3=image, 4=table, 5=text+image, 6=text+table */
     dataType?: 1 | 2 | 3 | 4 | 5 | 6;
     /** Path keywords for include/exclude filtering */
@@ -637,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.
@@ -651,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 */
@@ -667,7 +733,19 @@ interface RetrievalQueryResponse {
     /** Echoed query text */
     query: string;
     /** Retrieval router path used by the API for this query */
-    routerUsed?: string;
+    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[];
 }
@@ -1010,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.js

@@ -844,6 +844,13 @@ async function parseResult(httpClient, resultUrl, options) {
   if (fullMdFile) {
     fullMarkdown = await fullMdFile.async("string");
   }
+  let docNav;
+  const docNavFile = zip.file("doc_nav.json");
+  if (docNavFile) {
+    const docNavContent = await docNavFile.async("string");
+    const rawDocNav = JSON.parse(docNavContent);
+    docNav = keysToCamel(rawDocNav);
+  }
   let hierarchy;
   const hierarchyFile = zip.file("hierarchy.json");
   if (hierarchyFile) {
@@ -877,13 +884,15 @@ async function parseResult(httpClient, resultUrl, options) {
   const result = {
     manifest,
     chunks,
-    chunksSlim,
+    docNav,
     fullMarkdown,
+    rawZip: zipBuffer,
+    // Legacy
+    chunksSlim,
     hierarchy,
     tocHierarchies,
     kbCsv,
     hierarchyViewHtml,
-    rawZip: zipBuffer,
     get textChunks() {
       return chunks.filter((c) => c.type === "text");
     },
@@ -905,6 +914,9 @@ async function parseResult(httpClient, resultUrl, options) {
     async save(directory) {
       await import_fs2.promises.mkdir(directory, { recursive: true });
       await import_fs2.promises.writeFile((0, import_path.join)(directory, "manifest.json"), JSON.stringify(manifest, null, 2));
+      if (docNav) {
+        await import_fs2.promises.writeFile((0, import_path.join)(directory, "doc_nav.json"), JSON.stringify(docNav, null, 2));
+      }
       await import_fs2.promises.writeFile((0, import_path.join)(directory, "chunks.json"), JSON.stringify(chunks, null, 2));
       if (chunksSlim) {
         await import_fs2.promises.writeFile(
@@ -960,56 +972,24 @@ function extractSlimChunks(payload) {
   }
   return [];
 }
-function getChunkMetadata(chunkData) {
-  if (!chunkData.metadata) {
-    return {};
-  }
-  return chunkData.metadata;
-}
 function getChunkFilePath(chunkData) {
-  const metadata = getChunkMetadata(chunkData);
-  return chunkData.filePath ?? metadata.filePath ?? chunkData.path;
-}
-function normalizePageNums(pageNums) {
-  if (!Array.isArray(pageNums)) {
-    return void 0;
-  }
-  const normalized = pageNums.filter((pageNum) => typeof pageNum === "number");
-  return normalized.length > 0 ? normalized : void 0;
-}
-function normalizeTokens(tokens) {
-  if (!Array.isArray(tokens)) {
-    return void 0;
-  }
-  if (!tokens.every((token) => typeof token === "string")) {
-    return void 0;
-  }
-  return tokens;
+  const metadata = chunkData.metadata;
+  return chunkData.filePath ?? metadata?.filePath ?? chunkData.path;
 }
-function normalizeTextChunk(chunkData) {
-  const metadata = getChunkMetadata(chunkData);
-  const connectTo = metadata.connectTo ?? chunkData.connectTo;
-  const relationships = metadata.relationships ?? chunkData.relationships;
+function buildTextChunk(chunkData) {
   return {
     chunkId: chunkData.chunkId ?? "",
     type: "text",
     content: chunkData.content ?? "",
     path: chunkData.path ?? "",
-    pageNums: normalizePageNums(metadata.pageNums ?? chunkData.pageNums),
-    length: metadata.length ?? chunkData.length ?? 0,
-    tokens: normalizeTokens(metadata.tokens ?? chunkData.tokens),
-    keywords: metadata.keywords ?? chunkData.keywords,
-    summary: metadata.summary ?? chunkData.summary,
-    ...connectTo !== void 0 && { connectTo },
-    ...relationships !== void 0 && { relationships }
+    metadata: chunkData.metadata ?? {}
   };
 }
 async function processChunk(zip, chunkData) {
   if (chunkData.type === "text") {
-    return normalizeTextChunk(chunkData);
+    return buildTextChunk(chunkData);
   }
   if (chunkData.type === "image") {
-    const metadata = getChunkMetadata(chunkData);
     const filePath = getChunkFilePath(chunkData);
     if (!filePath) {
       throw new KnowhereError(`Image chunk missing file path: ${chunkData.chunkId ?? "unknown"}`);
@@ -1025,11 +1005,9 @@ async function processChunk(zip, chunkData) {
       type: "image",
       content: chunkData.content ?? "",
       path: chunkData.path ?? "",
-      pageNums: normalizePageNums(metadata.pageNums ?? chunkData.pageNums),
-      length: metadata.length ?? chunkData.length ?? 0,
       filePath,
-      summary: metadata.summary ?? chunkData.summary,
       data: imageBuffer,
+      metadata: chunkData.metadata ?? {},
       get format() {
         return getFileExtension(this.filePath);
       },
@@ -1044,7 +1022,6 @@ async function processChunk(zip, chunkData) {
     return enrichedChunk;
   }
   if (chunkData.type === "table") {
-    const metadata = getChunkMetadata(chunkData);
     const filePath = getChunkFilePath(chunkData);
     if (!filePath) {
       throw new KnowhereError(`Table chunk missing file path: ${chunkData.chunkId ?? "unknown"}`);
@@ -1060,12 +1037,9 @@ async function processChunk(zip, chunkData) {
       type: "table",
       content: chunkData.content ?? "",
       path: chunkData.path ?? "",
-      pageNums: normalizePageNums(metadata.pageNums ?? chunkData.pageNums),
-      length: metadata.length ?? chunkData.length ?? 0,
       filePath,
-      tableType: metadata.tableType ?? chunkData.tableType,
-      summary: metadata.summary ?? chunkData.summary,
       html,
+      metadata: chunkData.metadata ?? {},
       async save(directory) {
         const outputPath = (0, import_path.join)(directory, sanitizePath(this.filePath));
         const outputDir = (0, import_path.dirname)(outputPath);
@@ -1076,7 +1050,7 @@ async function processChunk(zip, chunkData) {
     };
     return enrichedChunk;
   }
-  return normalizeTextChunk(chunkData);
+  return buildTextChunk(chunkData);
 }
 
 // src/resources/jobs.ts

package/dist/index.mjs

@@ -784,6 +784,13 @@ async function parseResult(httpClient, resultUrl, options) {
   if (fullMdFile) {
     fullMarkdown = await fullMdFile.async("string");
   }
+  let docNav;
+  const docNavFile = zip.file("doc_nav.json");
+  if (docNavFile) {
+    const docNavContent = await docNavFile.async("string");
+    const rawDocNav = JSON.parse(docNavContent);
+    docNav = keysToCamel(rawDocNav);
+  }
   let hierarchy;
   const hierarchyFile = zip.file("hierarchy.json");
   if (hierarchyFile) {
@@ -817,13 +824,15 @@ async function parseResult(httpClient, resultUrl, options) {
   const result = {
     manifest,
     chunks,
-    chunksSlim,
+    docNav,
     fullMarkdown,
+    rawZip: zipBuffer,
+    // Legacy
+    chunksSlim,
     hierarchy,
     tocHierarchies,
     kbCsv,
     hierarchyViewHtml,
-    rawZip: zipBuffer,
     get textChunks() {
       return chunks.filter((c) => c.type === "text");
     },
@@ -845,6 +854,9 @@ async function parseResult(httpClient, resultUrl, options) {
     async save(directory) {
       await fs2.mkdir(directory, { recursive: true });
       await fs2.writeFile(join(directory, "manifest.json"), JSON.stringify(manifest, null, 2));
+      if (docNav) {
+        await fs2.writeFile(join(directory, "doc_nav.json"), JSON.stringify(docNav, null, 2));
+      }
       await fs2.writeFile(join(directory, "chunks.json"), JSON.stringify(chunks, null, 2));
       if (chunksSlim) {
         await fs2.writeFile(
@@ -900,56 +912,24 @@ function extractSlimChunks(payload) {
   }
   return [];
 }
-function getChunkMetadata(chunkData) {
-  if (!chunkData.metadata) {
-    return {};
-  }
-  return chunkData.metadata;
-}
 function getChunkFilePath(chunkData) {
-  const metadata = getChunkMetadata(chunkData);
-  return chunkData.filePath ?? metadata.filePath ?? chunkData.path;
-}
-function normalizePageNums(pageNums) {
-  if (!Array.isArray(pageNums)) {
-    return void 0;
-  }
-  const normalized = pageNums.filter((pageNum) => typeof pageNum === "number");
-  return normalized.length > 0 ? normalized : void 0;
-}
-function normalizeTokens(tokens) {
-  if (!Array.isArray(tokens)) {
-    return void 0;
-  }
-  if (!tokens.every((token) => typeof token === "string")) {
-    return void 0;
-  }
-  return tokens;
+  const metadata = chunkData.metadata;
+  return chunkData.filePath ?? metadata?.filePath ?? chunkData.path;
 }
-function normalizeTextChunk(chunkData) {
-  const metadata = getChunkMetadata(chunkData);
-  const connectTo = metadata.connectTo ?? chunkData.connectTo;
-  const relationships = metadata.relationships ?? chunkData.relationships;
+function buildTextChunk(chunkData) {
   return {
     chunkId: chunkData.chunkId ?? "",
     type: "text",
     content: chunkData.content ?? "",
     path: chunkData.path ?? "",
-    pageNums: normalizePageNums(metadata.pageNums ?? chunkData.pageNums),
-    length: metadata.length ?? chunkData.length ?? 0,
-    tokens: normalizeTokens(metadata.tokens ?? chunkData.tokens),
-    keywords: metadata.keywords ?? chunkData.keywords,
-    summary: metadata.summary ?? chunkData.summary,
-    ...connectTo !== void 0 && { connectTo },
-    ...relationships !== void 0 && { relationships }
+    metadata: chunkData.metadata ?? {}
   };
 }
 async function processChunk(zip, chunkData) {
   if (chunkData.type === "text") {
-    return normalizeTextChunk(chunkData);
+    return buildTextChunk(chunkData);
   }
   if (chunkData.type === "image") {
-    const metadata = getChunkMetadata(chunkData);
     const filePath = getChunkFilePath(chunkData);
     if (!filePath) {
       throw new KnowhereError(`Image chunk missing file path: ${chunkData.chunkId ?? "unknown"}`);
@@ -965,11 +945,9 @@ async function processChunk(zip, chunkData) {
       type: "image",
       content: chunkData.content ?? "",
       path: chunkData.path ?? "",
-      pageNums: normalizePageNums(metadata.pageNums ?? chunkData.pageNums),
-      length: metadata.length ?? chunkData.length ?? 0,
       filePath,
-      summary: metadata.summary ?? chunkData.summary,
       data: imageBuffer,
+      metadata: chunkData.metadata ?? {},
       get format() {
         return getFileExtension(this.filePath);
       },
@@ -984,7 +962,6 @@ async function processChunk(zip, chunkData) {
     return enrichedChunk;
   }
   if (chunkData.type === "table") {
-    const metadata = getChunkMetadata(chunkData);
     const filePath = getChunkFilePath(chunkData);
     if (!filePath) {
       throw new KnowhereError(`Table chunk missing file path: ${chunkData.chunkId ?? "unknown"}`);
@@ -1000,12 +977,9 @@ async function processChunk(zip, chunkData) {
       type: "table",
       content: chunkData.content ?? "",
       path: chunkData.path ?? "",
-      pageNums: normalizePageNums(metadata.pageNums ?? chunkData.pageNums),
-      length: metadata.length ?? chunkData.length ?? 0,
       filePath,
-      tableType: metadata.tableType ?? chunkData.tableType,
-      summary: metadata.summary ?? chunkData.summary,
       html,
+      metadata: chunkData.metadata ?? {},
       async save(directory) {
         const outputPath = join(directory, sanitizePath(this.filePath));
         const outputDir = dirname(outputPath);
@@ -1016,7 +990,7 @@ async function processChunk(zip, chunkData) {
     };
     return enrichedChunk;
   }
-  return normalizeTextChunk(chunkData);
+  return buildTextChunk(chunkData);
 }
 
 // src/resources/jobs.ts

package/package.json

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