@ontos-ai/knowhere-sdk 2.1.3 → 2.2.0

package/README.md

@@ -145,6 +145,56 @@ const result = await client.parse({
 });
 ```
 
+### Bring Your Own Key (BYOK)
+
+Pass per-request LLM credentials via `llmConfig` on parse/job create and
+retrieval queries. Flat root applies to both channels; use `models` for
+different model ids on the same endpoint, or `text` / `vision` for different
+provider endpoints. Use camelCase in TypeScript; the HTTP client serializes to
+snake_case on the wire.
+
+```typescript
+// Multimodal shorthand — one model for text + vision
+const llmConfig = {
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'gpt-4o',
+  baseUrl: 'https://api.openai.com/v1',
+};
+
+// Same endpoint, different models per channel
+const modelsConfig = {
+  apiKey: process.env.OPENAI_API_KEY,
+  baseUrl: 'https://api.openai.com/v1',
+  models: { text: 'gpt-4o-mini', vision: 'gpt-4o' },
+};
+
+// Or two different endpoints
+const splitLlmConfig = {
+  text: {
+    apiKey: process.env.OPENAI_API_KEY,
+    model: 'gpt-4o-mini',
+    baseUrl: 'https://api.openai.com/v1',
+  },
+  vision: {
+    apiKey: process.env.DASHSCOPE_API_KEY,
+    model: 'qwen-vl-max',
+    baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+  },
+};
+
+const result = await client.parse({
+  url: 'https://example.com/doc.pdf',
+  llmConfig: modelsConfig,
+});
+
+const response = await client.retrieval.query({
+  namespace: 'support-center',
+  query: 'What is the refund policy?',
+  useAgentic: true,
+  llmConfig: splitLlmConfig,
+});
+```
+
 ### Page Citation Assets
 
 Page citation assets are generated by Knowhere during page-memory parsing. The
@@ -373,6 +423,7 @@ const grep = await client.knowledge.grepChunks({
   pattern: 'warranty',
   maxResults: 10,
 });
+// grep.matches include pageNumbers when the source chunk has them.
 
 const serverSearch = await client.knowledge.search({
   query: 'battery warranty',

package/dist/index.d.mts

@@ -516,6 +516,47 @@ interface WebhookConfig {
     /** Webhook URL to notify on job completion */
     url: string;
 }
+/**
+ * Per-provider BYOK credentials and routing overrides.
+ */
+interface LlmProviderConfig {
+    /** Provider API key */
+    apiKey?: string;
+    /** Model identifier */
+    model?: string;
+    /** Provider base URL override */
+    baseUrl?: string;
+}
+/**
+ * Per-channel model ids that share root apiKey / baseUrl.
+ */
+interface LlmModelsConfig {
+    /** Text / planning model id */
+    text?: string;
+    /** Vision / VLM model id */
+    vision?: string;
+}
+/**
+ * Bring-your-own-key LLM configuration.
+ *
+ * Flat root (`apiKey` / `model` / `baseUrl`) applies to both channels.
+ * Use `models` for different model ids on the same endpoint, or `text` /
+ * `vision` objects for different provider endpoints.
+ */
+interface LlmConfig {
+    /** Default provider API key (with model/models + baseUrl) */
+    apiKey?: string;
+    /** Default model for both channels (overridden by models.*) */
+    model?: string;
+    /** Default OpenAI-compatible base URL */
+    baseUrl?: string;
+    /** Per-channel model ids sharing root apiKey / baseUrl */
+    models?: LlmModelsConfig;
+    /** Text / chat credentials (replaces root for text) */
+    text?: LlmProviderConfig;
+    /** Vision / VLM credentials (replaces root for vision) */
+    vision?: LlmProviderConfig;
+}
 /**
  * Client-provided display metadata copied onto the published document.
  */
@@ -540,6 +581,8 @@ interface CreateJobParams {
     documentMetadata?: DocumentMetadata;
     /** Parsing configuration */
     parsingParams?: ParsingParams;
+    /** Bring-your-own-key LLM credentials for this job */
+    llmConfig?: LlmConfig;
     /** Webhook configuration */
     webhook?: WebhookConfig;
 }
@@ -621,6 +664,8 @@ interface ParseParams {
      * assets into application-owned storage before the result is returned.
      */
     storageAdapter?: KnowhereAssetStorageOptions;
+    /** Bring-your-own-key LLM credentials for this parse */
+    llmConfig?: LlmConfig;
     /** Webhook configuration */
     webhook?: WebhookConfig;
     /** Upload progress callback */
@@ -733,7 +778,10 @@ declare abstract class BaseResource {
 declare class Jobs extends BaseResource {
     private pendingUploadJobs;
     /**
-     * Create a new parsing job
+     * Create a new parsing job.
+     *
+     * Auto-attaches `documentMetadata.createdByClient` / `clientVersion` for
+     * OSS telemetry. Caller-provided metadata keys win; defaults fill gaps only.
      */
     create(params: CreateJobParams): Promise<Job>;
     /**
@@ -815,6 +863,8 @@ interface RetrievalQueryParams {
     excludeDocumentIds?: string[];
     /** Document sections to exclude for this request only */
     excludeSections?: RetrievalSectionExclusion[];
+    /** Bring-your-own-key LLM credentials for this query */
+    llmConfig?: LlmConfig;
 }
 /**
  * Caller-facing source reference attached to a retrieval result.
@@ -1305,6 +1355,8 @@ interface KnowledgeGrepMatch {
     startOffset: number;
     endOffset: number;
     snippet: string;
+    /** Copied from the source chunk when the indexed chunk has page numbers. */
+    pageNumbers?: number[];
 }
 interface KnowledgeGrepResponse {
     document: LocalKnowledgeDocument;
@@ -1488,7 +1540,26 @@ declare class Knowhere {
     startParse(params: ParseParams): Promise<Job>;
 }
 
-declare const VERSION = "0.1.0";
+declare const VERSION = "2.1.3";
+
+/**
+ * Official Knowhere client identity written into job `document_metadata`.
+ *
+ * Wire format (snake_case on the wire after HTTP serialization):
+ * `{ created_by_client, client_version }`.
+ *
+ * Merge rule used by every official client: caller-provided keys win;
+ * defaults only fill keys that are missing.
+ */
+declare const NODE_SDK_DOCUMENT_METADATA_DEFAULTS: {
+    readonly createdByClient: "node-sdk";
+    readonly clientVersion: "2.1.3";
+};
+/**
+ * Merge official-client defaults under caller-provided document metadata.
+ * Existing keys on `provided` are preserved; defaults fill gaps only.
+ */
+declare function mergeDocumentMetadataDefaults(defaults: DocumentMetadata, provided?: DocumentMetadata | null): DocumentMetadata;
 
 declare function storeParseResultAssets(result: ParseResult, options?: KnowhereAssetStorageOptions): Promise<KnowhereAssetStorageResult>;
 
@@ -1651,4 +1722,4 @@ declare class JobFailedError extends KnowhereError {
     constructor(message: string, code: string, jobResult: JobResult);
 }
 
-export { APIError, type AuthTokenProvider, AuthenticationError, BadRequestError, type BaseChunk, ChecksumError, type Chunk, ConflictError, type CreateJobParams, DiskParsedDocumentStorage, type DocType, type Document, type DocumentChunk, type DocumentChunkGetParams, type DocumentChunkListParams, type DocumentChunkListResponse, type DocumentChunkPagination, type DocumentChunkResponse, type DocumentChunkType, type DocumentListPagination, type DocumentListParams, type DocumentListResponse, type DocumentMetadata, type DocumentPageCitationSource, Documents, type FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, type KnowhereAssetStorageAdapter, type KnowhereAssetStorageBody, type KnowhereAssetStorageHead, type KnowhereAssetStorageObject, type KnowhereAssetStorageOptions, type KnowhereAssetStorageResult, type KnowhereAssetStorageWriteResult, KnowhereError, type KnowhereOptions, Knowledge, type KnowledgeAsyncJobStatusResponse, type KnowledgeAsyncParseParams, type KnowledgeAsyncParseResponse, type KnowledgeCacheDocumentParams, type KnowledgeCacheJobResultParams, type KnowledgeChunkType, type KnowledgeDocumentReference, type KnowledgeGrepMatch, type KnowledgeGrepParams, type KnowledgeGrepResponse, type KnowledgeImportJobResultParams, type KnowledgeJobResultResponse, type KnowledgeLoadJobResultParams, type KnowledgeOutline, type KnowledgeParseParams, type KnowledgeParsedStorageOptions, type KnowledgeReadChunk, type KnowledgeReadParams, type KnowledgeReadResponse, type KnowledgeSearchParams, type KnowledgeSearchReference, type KnowledgeSearchResponse, type KnowledgeSearchResult, type KnowledgeSection, type KnowledgeStartupRecoveryResponse, type KnowledgeSyncParsedDocumentParams, type KnowledgeSyncParsedDocumentResponse, type LoadOptions, type LocalKnowledgeDocument, type LocalKnowledgeParseResponse, LocalKnowledgeStore, type Manifest, NetworkError, NotFoundError, type PageChunk, type PageCitationAsset, type PageCitationAssetContentType, type PageCitationAssetSource, type ParseParams, type ParseResult, type ParsedDocumentCommit, type ParsedDocumentCommitSource, type ParsedDocumentObject, type ParsedDocumentObjectHead, type ParsedDocumentObjectParams, type ParsedDocumentRevisionParams, type ParsedDocumentStorage, type ParsedDocumentStorageConfig, type ParsedDocumentStorageDocument, type ParsedDocumentStorageLimits, type ParsedDocumentSyncProgress, type ParsedDocumentSyncScheduler, type ParsedDocumentWriteObjectParams, type ParsedDocumentWriteObjectResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, Retrieval, type RetrievalChannel, type RetrievalChunkType, 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, storeParseResultAssets, syncParseResultToParsedDocumentStorage };
+export { APIError, type AuthTokenProvider, AuthenticationError, BadRequestError, type BaseChunk, ChecksumError, type Chunk, ConflictError, type CreateJobParams, DiskParsedDocumentStorage, type DocType, type Document, type DocumentChunk, type DocumentChunkGetParams, type DocumentChunkListParams, type DocumentChunkListResponse, type DocumentChunkPagination, type DocumentChunkResponse, type DocumentChunkType, type DocumentListPagination, type DocumentListParams, type DocumentListResponse, type DocumentMetadata, type DocumentPageCitationSource, Documents, type FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, type KnowhereAssetStorageAdapter, type KnowhereAssetStorageBody, type KnowhereAssetStorageHead, type KnowhereAssetStorageObject, type KnowhereAssetStorageOptions, type KnowhereAssetStorageResult, type KnowhereAssetStorageWriteResult, KnowhereError, type KnowhereOptions, Knowledge, type KnowledgeAsyncJobStatusResponse, type KnowledgeAsyncParseParams, type KnowledgeAsyncParseResponse, type KnowledgeCacheDocumentParams, type KnowledgeCacheJobResultParams, type KnowledgeChunkType, type KnowledgeDocumentReference, type KnowledgeGrepMatch, type KnowledgeGrepParams, type KnowledgeGrepResponse, type KnowledgeImportJobResultParams, type KnowledgeJobResultResponse, type KnowledgeLoadJobResultParams, type KnowledgeOutline, type KnowledgeParseParams, type KnowledgeParsedStorageOptions, type KnowledgeReadChunk, type KnowledgeReadParams, type KnowledgeReadResponse, type KnowledgeSearchParams, type KnowledgeSearchReference, type KnowledgeSearchResponse, type KnowledgeSearchResult, type KnowledgeSection, type KnowledgeStartupRecoveryResponse, type KnowledgeSyncParsedDocumentParams, type KnowledgeSyncParsedDocumentResponse, type LlmConfig, type LlmModelsConfig, type LlmProviderConfig, type LoadOptions, type LocalKnowledgeDocument, type LocalKnowledgeParseResponse, LocalKnowledgeStore, type Manifest, NODE_SDK_DOCUMENT_METADATA_DEFAULTS, NetworkError, NotFoundError, type PageChunk, type PageCitationAsset, type PageCitationAssetContentType, type PageCitationAssetSource, type ParseParams, type ParseResult, type ParsedDocumentCommit, type ParsedDocumentCommitSource, type ParsedDocumentObject, type ParsedDocumentObjectHead, type ParsedDocumentObjectParams, type ParsedDocumentRevisionParams, type ParsedDocumentStorage, type ParsedDocumentStorageConfig, type ParsedDocumentStorageDocument, type ParsedDocumentStorageLimits, type ParsedDocumentSyncProgress, type ParsedDocumentSyncScheduler, type ParsedDocumentWriteObjectParams, type ParsedDocumentWriteObjectResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, Retrieval, type RetrievalChannel, type RetrievalChunkType, 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, mergeDocumentMetadataDefaults, storeParseResultAssets, syncParseResultToParsedDocumentStorage };

package/dist/index.d.ts

@@ -516,6 +516,47 @@ interface WebhookConfig {
     /** Webhook URL to notify on job completion */
     url: string;
 }
+/**
+ * Per-provider BYOK credentials and routing overrides.
+ */
+interface LlmProviderConfig {
+    /** Provider API key */
+    apiKey?: string;
+    /** Model identifier */
+    model?: string;
+    /** Provider base URL override */
+    baseUrl?: string;
+}
+/**
+ * Per-channel model ids that share root apiKey / baseUrl.
+ */
+interface LlmModelsConfig {
+    /** Text / planning model id */
+    text?: string;
+    /** Vision / VLM model id */
+    vision?: string;
+}
+/**
+ * Bring-your-own-key LLM configuration.
+ *
+ * Flat root (`apiKey` / `model` / `baseUrl`) applies to both channels.
+ * Use `models` for different model ids on the same endpoint, or `text` /
+ * `vision` objects for different provider endpoints.
+ */
+interface LlmConfig {
+    /** Default provider API key (with model/models + baseUrl) */
+    apiKey?: string;
+    /** Default model for both channels (overridden by models.*) */
+    model?: string;
+    /** Default OpenAI-compatible base URL */
+    baseUrl?: string;
+    /** Per-channel model ids sharing root apiKey / baseUrl */
+    models?: LlmModelsConfig;
+    /** Text / chat credentials (replaces root for text) */
+    text?: LlmProviderConfig;
+    /** Vision / VLM credentials (replaces root for vision) */
+    vision?: LlmProviderConfig;
+}
 /**
  * Client-provided display metadata copied onto the published document.
  */
@@ -540,6 +581,8 @@ interface CreateJobParams {
     documentMetadata?: DocumentMetadata;
     /** Parsing configuration */
     parsingParams?: ParsingParams;
+    /** Bring-your-own-key LLM credentials for this job */
+    llmConfig?: LlmConfig;
     /** Webhook configuration */
     webhook?: WebhookConfig;
 }
@@ -621,6 +664,8 @@ interface ParseParams {
      * assets into application-owned storage before the result is returned.
      */
     storageAdapter?: KnowhereAssetStorageOptions;
+    /** Bring-your-own-key LLM credentials for this parse */
+    llmConfig?: LlmConfig;
     /** Webhook configuration */
     webhook?: WebhookConfig;
     /** Upload progress callback */
@@ -733,7 +778,10 @@ declare abstract class BaseResource {
 declare class Jobs extends BaseResource {
     private pendingUploadJobs;
     /**
-     * Create a new parsing job
+     * Create a new parsing job.
+     *
+     * Auto-attaches `documentMetadata.createdByClient` / `clientVersion` for
+     * OSS telemetry. Caller-provided metadata keys win; defaults fill gaps only.
      */
     create(params: CreateJobParams): Promise<Job>;
     /**
@@ -815,6 +863,8 @@ interface RetrievalQueryParams {
     excludeDocumentIds?: string[];
     /** Document sections to exclude for this request only */
     excludeSections?: RetrievalSectionExclusion[];
+    /** Bring-your-own-key LLM credentials for this query */
+    llmConfig?: LlmConfig;
 }
 /**
  * Caller-facing source reference attached to a retrieval result.
@@ -1305,6 +1355,8 @@ interface KnowledgeGrepMatch {
     startOffset: number;
     endOffset: number;
     snippet: string;
+    /** Copied from the source chunk when the indexed chunk has page numbers. */
+    pageNumbers?: number[];
 }
 interface KnowledgeGrepResponse {
     document: LocalKnowledgeDocument;
@@ -1488,7 +1540,26 @@ declare class Knowhere {
     startParse(params: ParseParams): Promise<Job>;
 }
 
-declare const VERSION = "0.1.0";
+declare const VERSION = "2.1.3";
+
+/**
+ * Official Knowhere client identity written into job `document_metadata`.
+ *
+ * Wire format (snake_case on the wire after HTTP serialization):
+ * `{ created_by_client, client_version }`.
+ *
+ * Merge rule used by every official client: caller-provided keys win;
+ * defaults only fill keys that are missing.
+ */
+declare const NODE_SDK_DOCUMENT_METADATA_DEFAULTS: {
+    readonly createdByClient: "node-sdk";
+    readonly clientVersion: "2.1.3";
+};
+/**
+ * Merge official-client defaults under caller-provided document metadata.
+ * Existing keys on `provided` are preserved; defaults fill gaps only.
+ */
+declare function mergeDocumentMetadataDefaults(defaults: DocumentMetadata, provided?: DocumentMetadata | null): DocumentMetadata;
 
 declare function storeParseResultAssets(result: ParseResult, options?: KnowhereAssetStorageOptions): Promise<KnowhereAssetStorageResult>;
 
@@ -1651,4 +1722,4 @@ declare class JobFailedError extends KnowhereError {
     constructor(message: string, code: string, jobResult: JobResult);
 }
 
-export { APIError, type AuthTokenProvider, AuthenticationError, BadRequestError, type BaseChunk, ChecksumError, type Chunk, ConflictError, type CreateJobParams, DiskParsedDocumentStorage, type DocType, type Document, type DocumentChunk, type DocumentChunkGetParams, type DocumentChunkListParams, type DocumentChunkListResponse, type DocumentChunkPagination, type DocumentChunkResponse, type DocumentChunkType, type DocumentListPagination, type DocumentListParams, type DocumentListResponse, type DocumentMetadata, type DocumentPageCitationSource, Documents, type FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, type KnowhereAssetStorageAdapter, type KnowhereAssetStorageBody, type KnowhereAssetStorageHead, type KnowhereAssetStorageObject, type KnowhereAssetStorageOptions, type KnowhereAssetStorageResult, type KnowhereAssetStorageWriteResult, KnowhereError, type KnowhereOptions, Knowledge, type KnowledgeAsyncJobStatusResponse, type KnowledgeAsyncParseParams, type KnowledgeAsyncParseResponse, type KnowledgeCacheDocumentParams, type KnowledgeCacheJobResultParams, type KnowledgeChunkType, type KnowledgeDocumentReference, type KnowledgeGrepMatch, type KnowledgeGrepParams, type KnowledgeGrepResponse, type KnowledgeImportJobResultParams, type KnowledgeJobResultResponse, type KnowledgeLoadJobResultParams, type KnowledgeOutline, type KnowledgeParseParams, type KnowledgeParsedStorageOptions, type KnowledgeReadChunk, type KnowledgeReadParams, type KnowledgeReadResponse, type KnowledgeSearchParams, type KnowledgeSearchReference, type KnowledgeSearchResponse, type KnowledgeSearchResult, type KnowledgeSection, type KnowledgeStartupRecoveryResponse, type KnowledgeSyncParsedDocumentParams, type KnowledgeSyncParsedDocumentResponse, type LoadOptions, type LocalKnowledgeDocument, type LocalKnowledgeParseResponse, LocalKnowledgeStore, type Manifest, NetworkError, NotFoundError, type PageChunk, type PageCitationAsset, type PageCitationAssetContentType, type PageCitationAssetSource, type ParseParams, type ParseResult, type ParsedDocumentCommit, type ParsedDocumentCommitSource, type ParsedDocumentObject, type ParsedDocumentObjectHead, type ParsedDocumentObjectParams, type ParsedDocumentRevisionParams, type ParsedDocumentStorage, type ParsedDocumentStorageConfig, type ParsedDocumentStorageDocument, type ParsedDocumentStorageLimits, type ParsedDocumentSyncProgress, type ParsedDocumentSyncScheduler, type ParsedDocumentWriteObjectParams, type ParsedDocumentWriteObjectResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, Retrieval, type RetrievalChannel, type RetrievalChunkType, 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, storeParseResultAssets, syncParseResultToParsedDocumentStorage };
+export { APIError, type AuthTokenProvider, AuthenticationError, BadRequestError, type BaseChunk, ChecksumError, type Chunk, ConflictError, type CreateJobParams, DiskParsedDocumentStorage, type DocType, type Document, type DocumentChunk, type DocumentChunkGetParams, type DocumentChunkListParams, type DocumentChunkListResponse, type DocumentChunkPagination, type DocumentChunkResponse, type DocumentChunkType, type DocumentListPagination, type DocumentListParams, type DocumentListResponse, type DocumentMetadata, type DocumentPageCitationSource, Documents, type FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, type KnowhereAssetStorageAdapter, type KnowhereAssetStorageBody, type KnowhereAssetStorageHead, type KnowhereAssetStorageObject, type KnowhereAssetStorageOptions, type KnowhereAssetStorageResult, type KnowhereAssetStorageWriteResult, KnowhereError, type KnowhereOptions, Knowledge, type KnowledgeAsyncJobStatusResponse, type KnowledgeAsyncParseParams, type KnowledgeAsyncParseResponse, type KnowledgeCacheDocumentParams, type KnowledgeCacheJobResultParams, type KnowledgeChunkType, type KnowledgeDocumentReference, type KnowledgeGrepMatch, type KnowledgeGrepParams, type KnowledgeGrepResponse, type KnowledgeImportJobResultParams, type KnowledgeJobResultResponse, type KnowledgeLoadJobResultParams, type KnowledgeOutline, type KnowledgeParseParams, type KnowledgeParsedStorageOptions, type KnowledgeReadChunk, type KnowledgeReadParams, type KnowledgeReadResponse, type KnowledgeSearchParams, type KnowledgeSearchReference, type KnowledgeSearchResponse, type KnowledgeSearchResult, type KnowledgeSection, type KnowledgeStartupRecoveryResponse, type KnowledgeSyncParsedDocumentParams, type KnowledgeSyncParsedDocumentResponse, type LlmConfig, type LlmModelsConfig, type LlmProviderConfig, type LoadOptions, type LocalKnowledgeDocument, type LocalKnowledgeParseResponse, LocalKnowledgeStore, type Manifest, NODE_SDK_DOCUMENT_METADATA_DEFAULTS, NetworkError, NotFoundError, type PageChunk, type PageCitationAsset, type PageCitationAssetContentType, type PageCitationAssetSource, type ParseParams, type ParseResult, type ParsedDocumentCommit, type ParsedDocumentCommitSource, type ParsedDocumentObject, type ParsedDocumentObjectHead, type ParsedDocumentObjectParams, type ParsedDocumentRevisionParams, type ParsedDocumentStorage, type ParsedDocumentStorageConfig, type ParsedDocumentStorageDocument, type ParsedDocumentStorageLimits, type ParsedDocumentSyncProgress, type ParsedDocumentSyncScheduler, type ParsedDocumentWriteObjectParams, type ParsedDocumentWriteObjectResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, Retrieval, type RetrievalChannel, type RetrievalChunkType, 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, mergeDocumentMetadataDefaults, storeParseResultAssets, syncParseResultToParsedDocumentStorage };

package/dist/index.js

@@ -46,6 +46,7 @@ __export(index_exports, {
   KnowhereError: () => KnowhereError,
   Knowledge: () => Knowledge,
   LocalKnowledgeStore: () => LocalKnowledgeStore,
+  NODE_SDK_DOCUMENT_METADATA_DEFAULTS: () => NODE_SDK_DOCUMENT_METADATA_DEFAULTS,
   NetworkError: () => NetworkError,
   NotFoundError: () => NotFoundError,
   PaymentRequiredError: () => PaymentRequiredError,
@@ -58,6 +59,7 @@ __export(index_exports, {
   VERSION: () => VERSION,
   ValidationError: () => ValidationError,
   default: () => Knowhere,
+  mergeDocumentMetadataDefaults: () => mergeDocumentMetadataDefaults,
   storeParseResultAssets: () => storeParseResultAssets,
   syncParseResultToParsedDocumentStorage: () => syncParseResultToParsedDocumentStorage
 });
@@ -70,7 +72,7 @@ var import_path3 = __toESM(require("path"));
 var import_axios = __toESM(require("axios"));
 
 // src/version.ts
-var VERSION = "0.1.0";
+var VERSION = "2.1.3";
 
 // src/constants.ts
 var DEFAULT_BASE_URL = "https://api.knowhereto.ai";
@@ -764,6 +766,18 @@ var BaseResource = class {
   }
 };
 
+// src/lib/document-metadata.ts
+var NODE_SDK_DOCUMENT_METADATA_DEFAULTS = {
+  createdByClient: "node-sdk",
+  clientVersion: VERSION
+};
+function mergeDocumentMetadataDefaults(defaults, provided) {
+  if (!provided) {
+    return { ...defaults };
+  }
+  return { ...defaults, ...provided };
+}
+
 // src/lib/upload.ts
 var import_fs = require("fs");
 async function uploadFile(httpClient, uploadUrl, file, options) {
@@ -1356,10 +1370,20 @@ function isMissingFileError(error) {
 var Jobs = class extends BaseResource {
   pendingUploadJobs = /* @__PURE__ */ new Map();
   /**
-   * Create a new parsing job
+   * Create a new parsing job.
+   *
+   * Auto-attaches `documentMetadata.createdByClient` / `clientVersion` for
+   * OSS telemetry. Caller-provided metadata keys win; defaults fill gaps only.
    */
   async create(params) {
-    const job = await this.httpClient.post(this.endpoint("/jobs"), params);
+    const documentMetadata = mergeDocumentMetadataDefaults(
+      NODE_SDK_DOCUMENT_METADATA_DEFAULTS,
+      params.documentMetadata
+    );
+    const job = await this.httpClient.post(this.endpoint("/jobs"), {
+      ...params,
+      documentMetadata
+    });
     if (job.uploadUrl) {
       this.pendingUploadJobs.set(job.jobId, job);
     }
@@ -2590,17 +2614,7 @@ var Knowledge = class _Knowledge {
       scannedChunks += 1;
       const chunkMatches = matcher(chunk.content);
       for (const match of chunkMatches) {
-        matches.push({
-          position: chunk.position,
-          chunkId: chunk.chunkId,
-          chunkType: chunk.chunkType,
-          sectionPath: chunk.sectionPath,
-          sourceChunkPath: chunk.sourceChunkPath,
-          filePath: chunk.filePath,
-          startOffset: match.startOffset,
-          endOffset: match.endOffset,
-          snippet: buildSnippet(chunk.content, match.startOffset, match.endOffset, contextChars)
-        });
+        matches.push(toGrepMatch(chunk, match, contextChars));
         if (matches.length >= maxResults) {
           return { document, matches, scannedChunks, truncated: true };
         }
@@ -2614,7 +2628,8 @@ var Knowledge = class _Knowledge {
       query: params.query,
       namespace: params.namespace,
       topK: params.topK,
-      useAgentic: params.useAgentic ?? false
+      // Omit when undefined so the API default (map-nav) applies; false → classic.
+      useAgentic: params.useAgentic
     });
     const documentByServerId = new Map(
       localDocuments.filter((document) => document.documentId).map((document) => [document.documentId, document])
@@ -2831,31 +2846,17 @@ var Knowledge = class _Knowledge {
         if (response.pagination.page === startPage && cursor?.nextChunkIndex !== void 0 && chunkIndex < cursor.nextChunkIndex) {
           continue;
         }
-        if (!matchesGrepScope(toIndexedRemoteChunk(chunk), params)) {
+        const indexed = toIndexedRemoteChunk(chunk);
+        if (!matchesGrepScope(indexed, params)) {
           continue;
         }
         scannedChunks += 1;
-        const chunkMatches = matcher(chunk.content ?? "");
+        const chunkMatches = matcher(indexed.content);
         for (const [matchIndex, match] of chunkMatches.entries()) {
           if (response.pagination.page === startPage && cursor?.nextChunkIndex === chunkIndex && cursor.nextMatchIndex !== void 0 && matchIndex < cursor.nextMatchIndex) {
             continue;
           }
-          matches.push({
-            position: toChunkPosition(chunk),
-            chunkId: chunk.chunkId,
-            chunkType: chunk.chunkType,
-            sectionPath: chunk.sectionPath ?? "",
-            sourceChunkPath: chunk.sourceChunkPath ?? chunk.sectionPath ?? "",
-            filePath: chunk.filePath ?? void 0,
-            startOffset: match.startOffset,
-            endOffset: match.endOffset,
-            snippet: buildSnippet(
-              chunk.content ?? "",
-              match.startOffset,
-              match.endOffset,
-              contextChars
-            )
-          });
+          matches.push(toGrepMatch(indexed, match, contextChars));
           if (matches.length >= maxResults) {
             const continuationCursor = createGrepContinuationCursor({
               documentId,
@@ -3019,17 +3020,7 @@ var Knowledge = class _Knowledge {
     for (const chunk of scopedChunks) {
       scannedChunks += 1;
       for (const match of matcher(chunk.content)) {
-        matches.push({
-          position: chunk.position,
-          chunkId: chunk.chunkId,
-          chunkType: chunk.chunkType,
-          sectionPath: chunk.sectionPath,
-          sourceChunkPath: chunk.sourceChunkPath,
-          filePath: chunk.filePath,
-          startOffset: match.startOffset,
-          endOffset: match.endOffset,
-          snippet: buildSnippet(chunk.content, match.startOffset, match.endOffset, contextChars)
-        });
+        matches.push(toGrepMatch(chunk, match, contextChars));
         if (matches.length >= maxResults) {
           return {
             document: createStoredKnowledgeDocument({
@@ -4059,6 +4050,20 @@ function toReadChunk(chunk) {
     metadata: chunk.metadata
   };
 }
+function toGrepMatch(chunk, match, contextChars) {
+  return {
+    position: chunk.position,
+    chunkId: chunk.chunkId,
+    chunkType: chunk.chunkType,
+    sectionPath: chunk.sectionPath,
+    sourceChunkPath: chunk.sourceChunkPath,
+    filePath: chunk.filePath,
+    startOffset: match.startOffset,
+    endOffset: match.endOffset,
+    snippet: buildSnippet(chunk.content, match.startOffset, match.endOffset, contextChars),
+    ...chunk.pageNumbers && chunk.pageNumbers.length > 0 ? { pageNumbers: [...chunk.pageNumbers] } : {}
+  };
+}
 function matchesGrepScope(chunk, params) {
   if (params.chunkType && chunk.chunkType !== params.chunkType) {
     return false;
@@ -4267,6 +4272,7 @@ var Knowhere = class {
       documentId: params.documentId,
       documentMetadata: params.documentMetadata,
       parsingParams: buildParsingParams(params),
+      llmConfig: params.llmConfig,
       webhook
     });
     if (params.file) {
@@ -4451,6 +4457,7 @@ function isMissingFileError3(error) {
   KnowhereError,
   Knowledge,
   LocalKnowledgeStore,
+  NODE_SDK_DOCUMENT_METADATA_DEFAULTS,
   NetworkError,
   NotFoundError,
   PaymentRequiredError,
@@ -4462,6 +4469,7 @@ function isMissingFileError3(error) {
   TimeoutError,
   VERSION,
   ValidationError,
+  mergeDocumentMetadataDefaults,
   storeParseResultAssets,
   syncParseResultToParsedDocumentStorage
 });

package/dist/index.mjs

@@ -7,7 +7,7 @@ import axios, {
 } from "axios";
 
 // src/version.ts
-var VERSION = "0.1.0";
+var VERSION = "2.1.3";
 
 // src/constants.ts
 var DEFAULT_BASE_URL = "https://api.knowhereto.ai";
@@ -701,6 +701,18 @@ var BaseResource = class {
   }
 };
 
+// src/lib/document-metadata.ts
+var NODE_SDK_DOCUMENT_METADATA_DEFAULTS = {
+  createdByClient: "node-sdk",
+  clientVersion: VERSION
+};
+function mergeDocumentMetadataDefaults(defaults, provided) {
+  if (!provided) {
+    return { ...defaults };
+  }
+  return { ...defaults, ...provided };
+}
+
 // src/lib/upload.ts
 import { createReadStream, promises as fs } from "fs";
 async function uploadFile(httpClient, uploadUrl, file, options) {
@@ -1293,10 +1305,20 @@ function isMissingFileError(error) {
 var Jobs = class extends BaseResource {
   pendingUploadJobs = /* @__PURE__ */ new Map();
   /**
-   * Create a new parsing job
+   * Create a new parsing job.
+   *
+   * Auto-attaches `documentMetadata.createdByClient` / `clientVersion` for
+   * OSS telemetry. Caller-provided metadata keys win; defaults fill gaps only.
    */
   async create(params) {
-    const job = await this.httpClient.post(this.endpoint("/jobs"), params);
+    const documentMetadata = mergeDocumentMetadataDefaults(
+      NODE_SDK_DOCUMENT_METADATA_DEFAULTS,
+      params.documentMetadata
+    );
+    const job = await this.httpClient.post(this.endpoint("/jobs"), {
+      ...params,
+      documentMetadata
+    });
     if (job.uploadUrl) {
       this.pendingUploadJobs.set(job.jobId, job);
     }
@@ -2527,17 +2549,7 @@ var Knowledge = class _Knowledge {
       scannedChunks += 1;
       const chunkMatches = matcher(chunk.content);
       for (const match of chunkMatches) {
-        matches.push({
-          position: chunk.position,
-          chunkId: chunk.chunkId,
-          chunkType: chunk.chunkType,
-          sectionPath: chunk.sectionPath,
-          sourceChunkPath: chunk.sourceChunkPath,
-          filePath: chunk.filePath,
-          startOffset: match.startOffset,
-          endOffset: match.endOffset,
-          snippet: buildSnippet(chunk.content, match.startOffset, match.endOffset, contextChars)
-        });
+        matches.push(toGrepMatch(chunk, match, contextChars));
         if (matches.length >= maxResults) {
           return { document, matches, scannedChunks, truncated: true };
         }
@@ -2551,7 +2563,8 @@ var Knowledge = class _Knowledge {
       query: params.query,
       namespace: params.namespace,
       topK: params.topK,
-      useAgentic: params.useAgentic ?? false
+      // Omit when undefined so the API default (map-nav) applies; false → classic.
+      useAgentic: params.useAgentic
     });
     const documentByServerId = new Map(
       localDocuments.filter((document) => document.documentId).map((document) => [document.documentId, document])
@@ -2768,31 +2781,17 @@ var Knowledge = class _Knowledge {
         if (response.pagination.page === startPage && cursor?.nextChunkIndex !== void 0 && chunkIndex < cursor.nextChunkIndex) {
           continue;
         }
-        if (!matchesGrepScope(toIndexedRemoteChunk(chunk), params)) {
+        const indexed = toIndexedRemoteChunk(chunk);
+        if (!matchesGrepScope(indexed, params)) {
           continue;
         }
         scannedChunks += 1;
-        const chunkMatches = matcher(chunk.content ?? "");
+        const chunkMatches = matcher(indexed.content);
         for (const [matchIndex, match] of chunkMatches.entries()) {
           if (response.pagination.page === startPage && cursor?.nextChunkIndex === chunkIndex && cursor.nextMatchIndex !== void 0 && matchIndex < cursor.nextMatchIndex) {
             continue;
           }
-          matches.push({
-            position: toChunkPosition(chunk),
-            chunkId: chunk.chunkId,
-            chunkType: chunk.chunkType,
-            sectionPath: chunk.sectionPath ?? "",
-            sourceChunkPath: chunk.sourceChunkPath ?? chunk.sectionPath ?? "",
-            filePath: chunk.filePath ?? void 0,
-            startOffset: match.startOffset,
-            endOffset: match.endOffset,
-            snippet: buildSnippet(
-              chunk.content ?? "",
-              match.startOffset,
-              match.endOffset,
-              contextChars
-            )
-          });
+          matches.push(toGrepMatch(indexed, match, contextChars));
           if (matches.length >= maxResults) {
             const continuationCursor = createGrepContinuationCursor({
               documentId,
@@ -2956,17 +2955,7 @@ var Knowledge = class _Knowledge {
     for (const chunk of scopedChunks) {
       scannedChunks += 1;
       for (const match of matcher(chunk.content)) {
-        matches.push({
-          position: chunk.position,
-          chunkId: chunk.chunkId,
-          chunkType: chunk.chunkType,
-          sectionPath: chunk.sectionPath,
-          sourceChunkPath: chunk.sourceChunkPath,
-          filePath: chunk.filePath,
-          startOffset: match.startOffset,
-          endOffset: match.endOffset,
-          snippet: buildSnippet(chunk.content, match.startOffset, match.endOffset, contextChars)
-        });
+        matches.push(toGrepMatch(chunk, match, contextChars));
         if (matches.length >= maxResults) {
           return {
             document: createStoredKnowledgeDocument({
@@ -3996,6 +3985,20 @@ function toReadChunk(chunk) {
     metadata: chunk.metadata
   };
 }
+function toGrepMatch(chunk, match, contextChars) {
+  return {
+    position: chunk.position,
+    chunkId: chunk.chunkId,
+    chunkType: chunk.chunkType,
+    sectionPath: chunk.sectionPath,
+    sourceChunkPath: chunk.sourceChunkPath,
+    filePath: chunk.filePath,
+    startOffset: match.startOffset,
+    endOffset: match.endOffset,
+    snippet: buildSnippet(chunk.content, match.startOffset, match.endOffset, contextChars),
+    ...chunk.pageNumbers && chunk.pageNumbers.length > 0 ? { pageNumbers: [...chunk.pageNumbers] } : {}
+  };
+}
 function matchesGrepScope(chunk, params) {
   if (params.chunkType && chunk.chunkType !== params.chunkType) {
     return false;
@@ -4204,6 +4207,7 @@ var Knowhere = class {
       documentId: params.documentId,
       documentMetadata: params.documentMetadata,
       parsingParams: buildParsingParams(params),
+      llmConfig: params.llmConfig,
       webhook
     });
     if (params.file) {
@@ -4387,6 +4391,7 @@ export {
   KnowhereError,
   Knowledge,
   LocalKnowledgeStore,
+  NODE_SDK_DOCUMENT_METADATA_DEFAULTS,
   NetworkError,
   NotFoundError,
   PaymentRequiredError,
@@ -4399,6 +4404,7 @@ export {
   VERSION,
   ValidationError,
   Knowhere as default,
+  mergeDocumentMetadataDefaults,
   storeParseResultAssets,
   syncParseResultToParsedDocumentStorage
 };

package/package.json

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