@ontos-ai/knowhere-sdk 0.3.1 → 0.5.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,17 @@ 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
+
 for (const result of response.results) {
   console.log(result.content);
   console.log(result.score);
@@ -224,10 +229,22 @@ const updateJob = await client.jobs.create({
 
 const documents = await client.documents.list({ namespace: 'support-center' });
 const document = await client.documents.get(documentId);
+const chunks = await client.documents.listChunks(documentId, {
+  page: 1,
+  pageSize: 50,
+  chunkType: 'text',
+});
 const archived = await client.documents.archive(documentId);
 
 console.log(documents.documents.length);
 console.log(document.status);
+console.log(chunks.pagination.total);
+if (chunks.chunks[0]) {
+  const chunk = await client.documents.getChunk(documentId, chunks.chunks[0].id, {
+    includeAssetUrls: true,
+  });
+  console.log(chunk.chunk.content);
+}
 console.log(archived.status);
 ```
 

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 */
@@ -668,6 +710,10 @@ interface RetrievalQueryResponse {
     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;
     /** Ranked retrieval results */
     results: RetrievalResult[];
 }
@@ -712,6 +758,104 @@ interface DocumentListResponse {
     /** Documents visible in the namespace */
     documents: Document[];
 }
+/**
+ * Document chunk types supported by document chunk endpoints.
+ */
+type DocumentChunkType = 'text' | 'image' | 'table';
+/**
+ * Pagination metadata returned by chunk list endpoints.
+ */
+interface DocumentChunkPagination {
+    /** Current page number */
+    page: number;
+    /** Number of items requested per page */
+    pageSize: number;
+    /** Total matching chunks */
+    total: number;
+    /** Total number of pages */
+    totalPages: number;
+}
+/**
+ * Query parameters for GET /v1/documents/{document_id}/chunks.
+ */
+interface DocumentChunkListParams {
+    /** Page number (default: 1) */
+    page?: number;
+    /** Items per page (default: 50, maximum: 200) */
+    pageSize?: number;
+    /** Optional chunk type filter */
+    chunkType?: DocumentChunkType;
+    /** Generate asset URLs for media chunks (default: false) */
+    includeAssetUrls?: boolean;
+}
+/**
+ * Query parameters for GET /v1/documents/{document_id}/chunks/{document_chunk_id}.
+ */
+interface DocumentChunkGetParams {
+    /** Generate asset URLs for media chunks (default: false) */
+    includeAssetUrls?: boolean;
+}
+/**
+ * One current-revision document chunk.
+ */
+interface DocumentChunk {
+    /** Stable document chunk row identifier */
+    id: string;
+    /** Parser-provided chunk identifier */
+    chunkId: string;
+    /** Chunk content type */
+    chunkType: DocumentChunkType;
+    /** Chunk text or generated summary content */
+    content?: string | null;
+    /** Parent section identifier */
+    sectionId?: string | null;
+    /** Parent section path */
+    sectionPath?: string | null;
+    /** Source path from the parser output */
+    sourceChunkPath?: string | null;
+    /** Generated artifact file path for media chunks */
+    filePath?: string | null;
+    /** Sort order within the document revision */
+    sortOrder: number;
+    /** Chunk metadata returned by the API */
+    metadata: Record<string, unknown>;
+    /** Generated asset URL when requested and available */
+    assetUrl?: string | null;
+    /** Chunk creation timestamp */
+    createdAt?: Date;
+}
+/**
+ * Response from GET /v1/documents/{document_id}/chunks.
+ */
+interface DocumentChunkListResponse {
+    /** Stable document identifier */
+    documentId: string;
+    /** Retrieval namespace */
+    namespace: string;
+    /** Current published job result identifier */
+    jobResultId?: string | null;
+    /** Current published job identifier */
+    jobId?: string | null;
+    /** Current-revision chunks */
+    chunks: DocumentChunk[];
+    /** Pagination metadata */
+    pagination: DocumentChunkPagination;
+}
+/**
+ * Response from GET /v1/documents/{document_id}/chunks/{document_chunk_id}.
+ */
+interface DocumentChunkResponse {
+    /** Stable document identifier */
+    documentId: string;
+    /** Retrieval namespace */
+    namespace: string;
+    /** Current published job result identifier */
+    jobResultId?: string | null;
+    /** Current published job identifier */
+    jobId?: string | null;
+    /** Requested current-revision chunk */
+    chunk: DocumentChunk;
+}
 
 /**
  * Resource for canonical document lifecycle operations.
@@ -727,10 +871,20 @@ declare class Documents extends BaseResource {
      * Get one canonical document by ID.
      */
     get(documentId: string): Promise<Document>;
+    /**
+     * List current-revision chunks for one canonical document.
+     */
+    listChunks(documentId: string, params?: DocumentChunkListParams): Promise<DocumentChunkListResponse>;
+    /**
+     * Get one current-revision chunk for one canonical document.
+     */
+    getChunk(documentId: string, documentChunkId: string, params?: DocumentChunkGetParams): Promise<DocumentChunkResponse>;
     /**
      * Archive one canonical document by ID.
      */
     archive(documentId: string): Promise<Document>;
+    private createChunkListRequestConfig;
+    private createChunkGetRequestConfig;
 }
 
 /**
@@ -902,4 +1056,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 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 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 */
@@ -668,6 +710,10 @@ interface RetrievalQueryResponse {
     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;
     /** Ranked retrieval results */
     results: RetrievalResult[];
 }
@@ -712,6 +758,104 @@ interface DocumentListResponse {
     /** Documents visible in the namespace */
     documents: Document[];
 }
+/**
+ * Document chunk types supported by document chunk endpoints.
+ */
+type DocumentChunkType = 'text' | 'image' | 'table';
+/**
+ * Pagination metadata returned by chunk list endpoints.
+ */
+interface DocumentChunkPagination {
+    /** Current page number */
+    page: number;
+    /** Number of items requested per page */
+    pageSize: number;
+    /** Total matching chunks */
+    total: number;
+    /** Total number of pages */
+    totalPages: number;
+}
+/**
+ * Query parameters for GET /v1/documents/{document_id}/chunks.
+ */
+interface DocumentChunkListParams {
+    /** Page number (default: 1) */
+    page?: number;
+    /** Items per page (default: 50, maximum: 200) */
+    pageSize?: number;
+    /** Optional chunk type filter */
+    chunkType?: DocumentChunkType;
+    /** Generate asset URLs for media chunks (default: false) */
+    includeAssetUrls?: boolean;
+}
+/**
+ * Query parameters for GET /v1/documents/{document_id}/chunks/{document_chunk_id}.
+ */
+interface DocumentChunkGetParams {
+    /** Generate asset URLs for media chunks (default: false) */
+    includeAssetUrls?: boolean;
+}
+/**
+ * One current-revision document chunk.
+ */
+interface DocumentChunk {
+    /** Stable document chunk row identifier */
+    id: string;
+    /** Parser-provided chunk identifier */
+    chunkId: string;
+    /** Chunk content type */
+    chunkType: DocumentChunkType;
+    /** Chunk text or generated summary content */
+    content?: string | null;
+    /** Parent section identifier */
+    sectionId?: string | null;
+    /** Parent section path */
+    sectionPath?: string | null;
+    /** Source path from the parser output */
+    sourceChunkPath?: string | null;
+    /** Generated artifact file path for media chunks */
+    filePath?: string | null;
+    /** Sort order within the document revision */
+    sortOrder: number;
+    /** Chunk metadata returned by the API */
+    metadata: Record<string, unknown>;
+    /** Generated asset URL when requested and available */
+    assetUrl?: string | null;
+    /** Chunk creation timestamp */
+    createdAt?: Date;
+}
+/**
+ * Response from GET /v1/documents/{document_id}/chunks.
+ */
+interface DocumentChunkListResponse {
+    /** Stable document identifier */
+    documentId: string;
+    /** Retrieval namespace */
+    namespace: string;
+    /** Current published job result identifier */
+    jobResultId?: string | null;
+    /** Current published job identifier */
+    jobId?: string | null;
+    /** Current-revision chunks */
+    chunks: DocumentChunk[];
+    /** Pagination metadata */
+    pagination: DocumentChunkPagination;
+}
+/**
+ * Response from GET /v1/documents/{document_id}/chunks/{document_chunk_id}.
+ */
+interface DocumentChunkResponse {
+    /** Stable document identifier */
+    documentId: string;
+    /** Retrieval namespace */
+    namespace: string;
+    /** Current published job result identifier */
+    jobResultId?: string | null;
+    /** Current published job identifier */
+    jobId?: string | null;
+    /** Requested current-revision chunk */
+    chunk: DocumentChunk;
+}
 
 /**
  * Resource for canonical document lifecycle operations.
@@ -727,10 +871,20 @@ declare class Documents extends BaseResource {
      * Get one canonical document by ID.
      */
     get(documentId: string): Promise<Document>;
+    /**
+     * List current-revision chunks for one canonical document.
+     */
+    listChunks(documentId: string, params?: DocumentChunkListParams): Promise<DocumentChunkListResponse>;
+    /**
+     * Get one current-revision chunk for one canonical document.
+     */
+    getChunk(documentId: string, documentChunkId: string, params?: DocumentChunkGetParams): Promise<DocumentChunkResponse>;
     /**
      * Archive one canonical document by ID.
      */
     archive(documentId: string): Promise<Document>;
+    private createChunkListRequestConfig;
+    private createChunkGetRequestConfig;
 }
 
 /**
@@ -902,4 +1056,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 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 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;
+  const metadata = chunkData.metadata;
+  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;
-}
-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
@@ -1219,12 +1193,59 @@ var Documents = class extends BaseResource {
   async get(documentId) {
     return this.httpClient.get(`/v1/documents/${documentId}`);
   }
+  /**
+   * List current-revision chunks for one canonical document.
+   */
+  async listChunks(documentId, params) {
+    return this.httpClient.get(
+      `/v1/documents/${documentId}/chunks`,
+      this.createChunkListRequestConfig(params)
+    );
+  }
+  /**
+   * Get one current-revision chunk for one canonical document.
+   */
+  async getChunk(documentId, documentChunkId, params) {
+    return this.httpClient.get(
+      `/v1/documents/${documentId}/chunks/${documentChunkId}`,
+      this.createChunkGetRequestConfig(params)
+    );
+  }
   /**
    * Archive one canonical document by ID.
    */
   async archive(documentId) {
     return this.httpClient.post(`/v1/documents/${documentId}/archive`);
   }
+  createChunkListRequestConfig(params) {
+    if (!params) {
+      return void 0;
+    }
+    const queryParams = {};
+    if (params.page !== void 0) {
+      queryParams.page = params.page;
+    }
+    if (params.pageSize !== void 0) {
+      queryParams.page_size = params.pageSize;
+    }
+    if (params.chunkType !== void 0) {
+      queryParams.chunk_type = params.chunkType;
+    }
+    if (params.includeAssetUrls === true) {
+      queryParams.include_asset_urls = true;
+    }
+    return Object.keys(queryParams).length > 0 ? { params: queryParams } : void 0;
+  }
+  createChunkGetRequestConfig(params) {
+    if (params?.includeAssetUrls !== true) {
+      return void 0;
+    }
+    return {
+      params: {
+        include_asset_urls: true
+      }
+    };
+  }
 };
 
 // src/client.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;
+  const metadata = chunkData.metadata;
+  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;
-}
-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
@@ -1159,12 +1133,59 @@ var Documents = class extends BaseResource {
   async get(documentId) {
     return this.httpClient.get(`/v1/documents/${documentId}`);
   }
+  /**
+   * List current-revision chunks for one canonical document.
+   */
+  async listChunks(documentId, params) {
+    return this.httpClient.get(
+      `/v1/documents/${documentId}/chunks`,
+      this.createChunkListRequestConfig(params)
+    );
+  }
+  /**
+   * Get one current-revision chunk for one canonical document.
+   */
+  async getChunk(documentId, documentChunkId, params) {
+    return this.httpClient.get(
+      `/v1/documents/${documentId}/chunks/${documentChunkId}`,
+      this.createChunkGetRequestConfig(params)
+    );
+  }
   /**
    * Archive one canonical document by ID.
    */
   async archive(documentId) {
     return this.httpClient.post(`/v1/documents/${documentId}/archive`);
   }
+  createChunkListRequestConfig(params) {
+    if (!params) {
+      return void 0;
+    }
+    const queryParams = {};
+    if (params.page !== void 0) {
+      queryParams.page = params.page;
+    }
+    if (params.pageSize !== void 0) {
+      queryParams.page_size = params.pageSize;
+    }
+    if (params.chunkType !== void 0) {
+      queryParams.chunk_type = params.chunkType;
+    }
+    if (params.includeAssetUrls === true) {
+      queryParams.include_asset_urls = true;
+    }
+    return Object.keys(queryParams).length > 0 ? { params: queryParams } : void 0;
+  }
+  createChunkGetRequestConfig(params) {
+    if (params?.includeAssetUrls !== true) {
+      return void 0;
+    }
+    return {
+      params: {
+        include_asset_urls: true
+      }
+    };
+  }
 };
 
 // src/client.ts

package/package.json

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