@ontos-ai/knowhere-sdk 2.0.0 → 2.1.2

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)
 
@@ -145,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:
@@ -299,12 +346,16 @@ 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 committed result-layout model.
 
 ```typescript
-const parsed = await client.knowledge.parse({
+const parsed = await client.knowledge.parseToLocalCache({
   file: './manual.pdf',
   localDocumentId: 'manual',
 });
@@ -334,27 +385,49 @@ 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 the expanded Knowhere result layout (`manifest.json`, `chunks.json`,
+sidecars, and assets), sync progress, and a final `.knowhere-sdk/commit.json`
+before returning. Partial storage writes are ignored until the commit marker is
+present.
 
 ```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;
+remote fallback requests asset URLs from the Knowhere API, and storage hits use
+stored object URLs when the configured storage can resolve them:
+
+```typescript
+const remoteRead = await knowledge.readChunks({
   documentId: 'doc_123',
-  sectionPath: 'Overview',
-  limit: 5,
+  page: 1,
+  pageSize: 20,
+  chunkType: 'page',
 });
 
-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',
   limit: 5,
@@ -383,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: