@ontos-ai/knowhere-sdk 0.10.0 → 2.1.1

package/README.md

@@ -23,7 +23,7 @@ npm install @ontos-ai/knowhere-sdk
 
 **Requirements:**
 
-- Node.js >= 20.19.0
+- Node.js >= 22.13.0
 - npm >= 10.0.0
 - TypeScript >= 5.0 (optional, for type checking)
 
@@ -46,6 +46,7 @@ const result = await client.parse({
 console.log(`Found ${result.textChunks.length} text chunks`);
 console.log(`Found ${result.imageChunks.length} images`);
 console.log(`Found ${result.tableChunks.length} tables`);
+console.log(`Found ${result.pageChunks.length} page chunks`);
 
 // Work with chunks — worker metadata is in chunk.metadata
 result.textChunks.forEach((chunk) => {
@@ -54,6 +55,12 @@ result.textChunks.forEach((chunk) => {
   console.log(chunk.metadata.summary);
 });
 
+result.pageChunks.forEach((chunk) => {
+  console.log(chunk.contentSource); // "summary"
+  console.log(chunk.content); // page-level summary
+  console.log(chunk.metadata.pageNums); // citation pages
+});
+
 // Save results to disk
 await result.save('./output/');
 ```
@@ -138,6 +145,53 @@ const result = await client.parse({
 });
 ```
 
+### Page Citation Assets
+
+Page citation assets are generated by Knowhere during page-memory parsing. The
+SDK does not render PDF pages locally; it preserves the page image descriptors
+returned by the server on page chunks and retrieval metadata.
+
+```typescript
+import Knowhere from '@ontos-ai/knowhere-sdk';
+
+const client = new Knowhere({ apiKey: process.env.KNOWHERE_API_KEY });
+
+const result = await client.parse({
+  file: './manual.pdf',
+});
+
+for (const chunk of result.pageChunks) {
+  console.log(chunk.metadata.pageAssets);
+}
+```
+
+`metadata.pageAssets` entries point at concrete page images stored with the Knowhere
+result. `artifactRef` is the durable result artifact path; `assetUrl` is an
+optional server-generated access URL.
+
+```typescript
+type PageCitationAsset = {
+  pageNum: number;
+  artifactRef: string;
+  assetUrl?: string;
+  contentType: 'image/png' | 'image/jpeg';
+  width?: number;
+  height?: number;
+  source: 'knowhere-rendered-page-citation-source';
+};
+```
+
+Document chunk APIs can include signed page image URLs when requested:
+
+```typescript
+const chunks = await client.documents.listChunks('doc_123', {
+  chunkType: 'page',
+  includeAssetUrls: true,
+});
+
+console.log(chunks.chunks[0]?.metadata.pageAssets?.[0]?.assetUrl);
+```
+
 ### Low-Level API
 
 For granular control over the job lifecycle:
@@ -200,6 +254,7 @@ console.log(documentId);
 const response = await client.retrieval.query({
   namespace: 'support-center',
   query: 'How do I reset Bluetooth pairing?',
+  chunkTypes: ['page'],
   topK: 5,
   useAgentic: true,
 });
@@ -212,7 +267,9 @@ console.log(response.failureReason); // no-answer reason, when returned
 
 for (const result of response.results) {
   console.log(result.content);
+  console.log(result.contentSource);
   console.log(result.score);
+  console.log(result.metadata?.pageNums);
   console.log(result.source.sourceFileName, result.source.sectionPath);
 }
 ```
@@ -221,9 +278,12 @@ Retrieval results use one canonical source object:
 
 ```typescript
 result.content;
+result.chunkId;
 result.chunkType;
+result.contentSource;
 result.score;
 result.assetUrl;
+result.metadata;
 result.source.documentId;
 result.source.sourceFileName;
 result.source.sectionPath;
@@ -237,10 +297,12 @@ const reference = response.referencedChunks[0];
 reference.chunkId;
 reference.documentId;
 reference.chunkType;
+reference.contentSource;
 reference.sectionPath;
 reference.filePath;
 reference.jobId;
 reference.assetUrl;
+reference.metadata;
 ```
 
 Use `documentId` to update or archive a document:
@@ -261,7 +323,7 @@ const document = await client.documents.get(documentId);
 const chunks = await client.documents.listChunks(documentId, {
   page: 1,
   pageSize: 50,
-  chunkType: 'image',
+  chunkType: 'page',
   includeAssetUrls: true,
 });
 const archived = await client.documents.archive(documentId);
@@ -275,6 +337,8 @@ if (chunks.chunks[0]) {
     includeAssetUrls: true,
   });
   console.log(chunk.chunk.content);
+  console.log(chunk.chunk.contentSource);
+  console.log(chunk.chunk.metadata.pageNums);
   console.log(chunk.chunk.assetUrl);
 }
 console.log(archived.status);
@@ -282,14 +346,18 @@ console.log(archived.status);
 
 ### Local Knowledge Tools
 
-The SDK can also keep parsed results in a local cache and run exact inspection
-tools over that cached copy. This is the implementation used by the separate
-`@ontos-ai/knowhere-mcp` package.
+The SDK can also run exact inspection tools over parsed results. Local import
+helpers still write under the SDK cache directory by design, while published
+`documentId` reads use configured parsed storage first and fall back to
+Knowhere's remote chunk API without importing the result ZIP into local disk.
+Server workflows can configure parsed storage with
+`client.knowledge.withParsedStorage(...)` so Notebook, MCP, and CLI surfaces
+share the same snapshot model.
 
 ```typescript
-const parsed = await client.knowledge.parse({
+const parsed = await client.knowledge.parseToLocalCache({
   file: './manual.pdf',
-  localDocumentId: 'manual-v1',
+  localDocumentId: 'manual',
 });
 
 const outline = await client.knowledge.getDocumentOutline(parsed.document.localDocumentId);
@@ -317,29 +385,51 @@ console.log(grep.matches);
 console.log(serverSearch.references);
 ```
 
-Local grep and reads use the cached parse result, not server-side chunk scans.
-Search uses the Knowhere API retrieval query; local document IDs only help map
-returned server document IDs back to local cache IDs when available.
-If a search result only has a published `documentId`, or an async parse flow only
-has a completed `jobId`, read-oriented helpers can accept that remote identifier
-directly and will sync the result into the local cache before reading. For a
-`documentId`, the SDK resolves the document's current published `jobId` and then
-downloads the parser result ZIP through the same `cacheJobResult(...)` path:
+Local grep and reads use the cached parse result. Published `documentId` grep
+streams `documents.listChunks(...)` page by page when parsed storage is missing
+or stale. Search uses the Knowhere API retrieval query; local document IDs only
+help map returned server document IDs back to local cache IDs when available.
+When `knowledge.parseToLocalCache(...)`, `knowledge.importJobResult(...)`, or
+`knowledge.loadJobResult(...)` runs with configured parsed storage, the SDK
+writes chunk pages, durable assets, sync progress, and a committed
+`manifest/current.json` before returning. Partial snapshots are ignored until
+the manifest is committed.
 
 ```typescript
-const remoteRead = await client.knowledge.readChunks({
+const knowledge = client.knowledge.withParsedStorage({
+  storage: myParsedDocumentStorage,
+  scheduler: myBackgroundScheduler,
+  limits: { remotePageSize: 100, maxPagesPerSync: 10 },
+});
+```
+
+If a search result only has a published `documentId`, read-oriented helpers can
+accept that remote identifier directly. `readChunks` supports display paging;
+`assetUrlPolicy: 'durable'` hardens only returned assets through configured
+storage and omits asset URLs if hardening fails:
+
+```typescript
+const remoteRead = await knowledge.readChunks({
   documentId: 'doc_123',
-  sectionPath: 'Overview',
-  limit: 5,
+  page: 1,
+  pageSize: 20,
+  chunkType: 'page',
+  assetUrlPolicy: 'durable',
 });
 
-const remoteOutline = await client.knowledge.getDocumentOutline({
+const remoteOutline = await knowledge.getDocumentOutline({
   documentId: 'doc_123',
 });
 
-const jobRead = await client.knowledge.readChunks({
+const grep = await knowledge.grepChunks({
+  documentId: 'doc_123',
+  pattern: 'warranty',
+  maxResults: 10,
+});
+
+const jobRead = await knowledge.readChunks({
   jobId: jobResult.jobId,
-  localDocumentId: 'manual-v1',
+  localDocumentId: 'manual',
   limit: 5,
 });
 ```
@@ -354,7 +444,7 @@ job completes:
 ```typescript
 const started = await client.knowledge.startParse({
   file: './manual.pdf',
-  localDocumentId: 'manual-v1',
+  localDocumentId: 'manual',
 });
 
 const status = await client.knowledge.getJobStatus(started.job.jobId);
@@ -366,9 +456,13 @@ if (status.job.isDone && status.cache.document) {
 
 When the job was started through `client.knowledge.startParse(...)`,
 `getJobStatus(...)` automatically caches the completed result locally the first
-time it observes `status.job.isDone`. Use `cacheJobResult(...)` only to recover a
-completed job that was not started through the local knowledge helper, or to
-retry a cache step explicitly.
+time it observes `status.job.isDone`. Use `importJobResult(...)` to recover a
+completed job into the local cache when it was not started through the local
+knowledge helper, or to retry a local import step explicitly. Use
+`loadJobResult(...)` for server workflows that should load a completed result
+without creating SDK local-disk cache state. Use `syncParsedDocument(...)` to
+explicitly resume or retry parsed-storage sync for an existing `documentId`,
+`jobId`, or local parsed result.
 
 Follow-up queries can exclude documents or sections for one request: