@ontos-ai/knowhere-sdk 0.6.0 → 0.8.0

package/dist/index.js

@@ -43,6 +43,8 @@ __export(index_exports, {
   Jobs: () => Jobs,
   Knowhere: () => Knowhere,
   KnowhereError: () => KnowhereError,
+  Knowledge: () => Knowledge,
+  LocalKnowledgeStore: () => LocalKnowledgeStore,
   NetworkError: () => NetworkError,
   NotFoundError: () => NotFoundError,
   PaymentRequiredError: () => PaymentRequiredError,
@@ -59,7 +61,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/client.ts
-var import_path2 = __toESM(require("path"));
+var import_path3 = __toESM(require("path"));
 
 // src/lib/http-client.ts
 var import_axios = __toESM(require("axios"));
@@ -101,6 +103,7 @@ var NetworkError = class extends KnowhereError {
     this.cause = cause;
     this.name = "NetworkError";
   }
+  cause;
 };
 var TimeoutError = class extends NetworkError {
   constructor(message = "Request timed out") {
@@ -114,6 +117,7 @@ var PollingTimeoutError = class extends KnowhereError {
     this.elapsedMs = elapsedMs;
     this.name = "PollingTimeoutError";
   }
+  elapsedMs;
 };
 var ChecksumError = class extends KnowhereError {
   constructor(message = "Checksum verification failed", expected, actual) {
@@ -122,6 +126,8 @@ var ChecksumError = class extends KnowhereError {
     this.actual = actual;
     this.name = "ChecksumError";
   }
+  expected;
+  actual;
 };
 var ValidationError = class extends KnowhereError {
   constructor(message) {
@@ -147,6 +153,11 @@ var APIError = class extends KnowhereError {
     this.body = body;
     this.name = "APIError";
   }
+  statusCode;
+  code;
+  requestId;
+  details;
+  body;
 };
 var BadRequestError = class extends APIError {
   constructor(message, code, requestId, details, body) {
@@ -190,6 +201,7 @@ var RateLimitError = class extends APIError {
     this.retryAfter = retryAfter;
     this.name = "RateLimitError";
   }
+  retryAfter;
 };
 var InternalServerError = class extends APIError {
   constructor(message = "Internal server error", code, requestId, details, body) {
@@ -245,11 +257,13 @@ var JobFailedError = class extends KnowhereError {
     this.jobResult = jobResult;
     this.name = "JobFailedError";
   }
+  code;
+  jobResult;
 };
 
 // src/lib/utils.ts
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 function snakeToCamel(str) {
   return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
@@ -355,8 +369,8 @@ function enrichParseResult(parseResult2, scope) {
   }
   return parseResult2;
 }
-function sanitizePath(path2) {
-  let sanitized = path2.replace(/^\/+/, "");
+function sanitizePath(path3) {
+  let sanitized = path3.replace(/^\/+/, "");
   sanitized = sanitized.replace(/\.\.(\/|\\)/g, "");
   sanitized = sanitized.replace(/\\/g, "/");
   return sanitized;
@@ -470,7 +484,7 @@ async function withRetry(fn, maxRetries, onRetry) {
       if (onRetry) {
         onRetry(attempt + 1, error);
       }
-      await new Promise((resolve) => setTimeout(resolve, delay));
+      await new Promise((resolve2) => setTimeout(resolve2, delay));
     }
   }
   throw lastError;
@@ -483,17 +497,19 @@ var HttpClient = class {
   uploadTimeout;
   httpAgent;
   httpsAgent;
+  authTokenProvider;
   constructor(options) {
     this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
     this.uploadTimeout = options.uploadTimeout ?? 6e5;
     this.httpAgent = options.httpAgent;
     this.httpsAgent = options.httpsAgent;
+    this.authTokenProvider = options.authTokenProvider;
     this.axios = import_axios.default.create({
       baseURL: options.baseURL,
       timeout: options.timeout ?? DEFAULT_TIMEOUT,
       headers: {
         "User-Agent": `knowhere-node-sdk/${VERSION}`,
-        Authorization: `Bearer ${options.apiKey}`,
+        ...options.apiKey ? { Authorization: `Bearer ${options.apiKey}` } : {},
         "Content-Type": "application/json",
         ...options.defaultHeaders
       },
@@ -505,6 +521,9 @@ var HttpClient = class {
   setupInterceptors() {
     this.axios.interceptors.request.use(
       (config) => {
+        if (this.authTokenProvider) {
+          return this.attachDynamicAuthorization(config);
+        }
         if (config.data && typeof config.data === "object") {
           config.data = keysToSnake(config.data);
         }
@@ -528,6 +547,19 @@ var HttpClient = class {
       }
     );
   }
+  async attachDynamicAuthorization(config) {
+    const token = await this.authTokenProvider?.();
+    if (!token) {
+      throw new ValidationError("Authentication token provider returned an empty token");
+    }
+    const headers = import_axios.AxiosHeaders.from(config.headers);
+    headers.set("Authorization", `Bearer ${token}`);
+    config.headers = headers;
+    if (config.data && typeof config.data === "object") {
+      config.data = keysToSnake(config.data);
+    }
+    return config;
+  }
   handleError(error) {
     if (!error.response) {
       if (error.code === "ECONNABORTED" || error.message.includes("timeout")) {
@@ -817,6 +849,9 @@ async function parseResult(httpClient, resultUrl, options) {
   const zipBuffer = await httpClient.download(resultUrl);
   if (options?.verifyChecksum !== false) {
   }
+  return parseResultBuffer(zipBuffer);
+}
+async function parseResultBuffer(zipBuffer) {
   const zip = await import_jszip.default.loadAsync(zipBuffer);
   const manifestFile = zip.file("manifest.json");
   if (!manifestFile) {
@@ -881,7 +916,7 @@ async function parseResult(httpClient, resultUrl, options) {
   if (hierarchyViewFile) {
     hierarchyViewHtml = await hierarchyViewFile.async("string");
   }
-  const result = {
+  return createParseResult({
     manifest,
     chunks,
     docNav,
@@ -892,6 +927,136 @@ async function parseResult(httpClient, resultUrl, options) {
     hierarchy,
     tocHierarchies,
     kbCsv,
+    hierarchyViewHtml
+  });
+}
+async function parseResultDirectory(directory) {
+  const manifestContent = await readRequiredTextFile(directory, "manifest.json");
+  let manifest = JSON.parse(manifestContent);
+  manifest = keysToCamel(manifest);
+  manifest = parseDates(manifest);
+  const chunksContent = await readRequiredTextFile(directory, "chunks.json");
+  let chunksData = JSON.parse(chunksContent);
+  chunksData = keysToCamel(chunksData);
+  const rawChunks = extractChunks(chunksData);
+  const chunks = [];
+  for (const chunkData of rawChunks) {
+    chunks.push(await processDirectoryChunk(directory, chunkData));
+  }
+  const fullMarkdown = await readOptionalTextFile(directory, "full.md");
+  const rawDocNav = await readOptionalJsonFile(directory, "doc_nav.json");
+  const docNav = rawDocNav === void 0 ? void 0 : keysToCamel(rawDocNav);
+  const hierarchy = await readOptionalJsonFile(directory, "hierarchy.json");
+  const rawChunksSlim = await readOptionalJsonFile(directory, "chunks_slim.json");
+  const chunksSlim = rawChunksSlim === void 0 ? void 0 : extractSlimChunks(keysToCamel(rawChunksSlim));
+  const rawTocHierarchies = await readOptionalJsonFile(directory, "toc_hierarchies.json");
+  const tocHierarchies = rawTocHierarchies === void 0 ? void 0 : keysToCamel(rawTocHierarchies);
+  const kbCsv = await readOptionalTextFile(directory, "kb.csv");
+  const hierarchyViewHtml = await readOptionalTextFile(directory, "hierarchy_view.html");
+  return createParseResult({
+    manifest,
+    chunks,
+    docNav,
+    fullMarkdown,
+    rawZip: Buffer.alloc(0),
+    chunksSlim,
+    hierarchy,
+    tocHierarchies,
+    kbCsv,
+    hierarchyViewHtml
+  });
+}
+async function saveExpandedParseResult(result, directory) {
+  if (result.rawZip.length > 0) {
+    const didExtractZip = await tryExtractRawZip(result.rawZip, directory);
+    if (didExtractZip) {
+      return directory;
+    }
+  }
+  await import_fs2.promises.mkdir(directory, { recursive: true });
+  await import_fs2.promises.writeFile((0, import_path.join)(directory, "manifest.json"), JSON.stringify(result.manifest, null, 2));
+  if (result.docNav) {
+    await import_fs2.promises.writeFile((0, import_path.join)(directory, "doc_nav.json"), JSON.stringify(result.docNav, null, 2));
+  }
+  await import_fs2.promises.writeFile(
+    (0, import_path.join)(directory, "chunks.json"),
+    JSON.stringify(serializeChunks(result.chunks), null, 2)
+  );
+  if (result.chunksSlim) {
+    await import_fs2.promises.writeFile(
+      (0, import_path.join)(directory, "chunks_slim.json"),
+      JSON.stringify({ chunks: result.chunksSlim }, null, 2)
+    );
+  }
+  if (result.fullMarkdown) {
+    await import_fs2.promises.writeFile((0, import_path.join)(directory, "full.md"), result.fullMarkdown);
+  }
+  if (result.hierarchy) {
+    await import_fs2.promises.writeFile(
+      (0, import_path.join)(directory, "hierarchy.json"),
+      JSON.stringify(result.hierarchy, null, 2)
+    );
+  }
+  if (result.tocHierarchies) {
+    await import_fs2.promises.writeFile(
+      (0, import_path.join)(directory, "toc_hierarchies.json"),
+      JSON.stringify(result.tocHierarchies, null, 2)
+    );
+  }
+  if (result.kbCsv) {
+    await import_fs2.promises.writeFile((0, import_path.join)(directory, "kb.csv"), result.kbCsv);
+  }
+  if (result.hierarchyViewHtml) {
+    await import_fs2.promises.writeFile((0, import_path.join)(directory, "hierarchy_view.html"), result.hierarchyViewHtml);
+  }
+  for (const imageChunk of result.imageChunks) {
+    await writeBinaryAsset(directory, imageChunk.filePath, imageChunk.data);
+  }
+  for (const tableChunk of result.tableChunks) {
+    await writeTextAsset(directory, tableChunk.filePath, tableChunk.html);
+  }
+  return directory;
+}
+async function tryExtractRawZip(zipBuffer, directory) {
+  try {
+    const zip = await import_jszip.default.loadAsync(zipBuffer);
+    await import_fs2.promises.mkdir(directory, { recursive: true });
+    for (const entry of Object.values(zip.files)) {
+      if (entry.dir || entry.name === "result.zip") {
+        continue;
+      }
+      const outputPath = resolveAssetPath(directory, entry.name);
+      await import_fs2.promises.mkdir((0, import_path.dirname)(outputPath), { recursive: true });
+      await import_fs2.promises.writeFile(outputPath, await entry.async("nodebuffer"));
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+function createParseResult(parts) {
+  const {
+    manifest,
+    chunks,
+    docNav,
+    fullMarkdown,
+    rawZip,
+    chunksSlim,
+    hierarchy,
+    tocHierarchies,
+    kbCsv,
+    hierarchyViewHtml
+  } = parts;
+  return {
+    manifest,
+    chunks,
+    docNav,
+    fullMarkdown,
+    rawZip,
+    chunksSlim,
+    hierarchy,
+    tocHierarchies,
+    kbCsv,
     hierarchyViewHtml,
     get textChunks() {
       return chunks.filter((c) => c.type === "text");
@@ -948,11 +1113,10 @@ async function parseResult(httpClient, resultUrl, options) {
       for (const tableChunk of this.tableChunks) {
         await tableChunk.save(directory);
       }
-      await import_fs2.promises.writeFile((0, import_path.join)(directory, "result.zip"), zipBuffer);
+      await import_fs2.promises.writeFile((0, import_path.join)(directory, "result.zip"), rawZip);
       return directory;
     }
   };
-  return result;
 }
 function extractChunks(payload) {
   if (Array.isArray(payload)) {
@@ -985,6 +1149,37 @@ function buildTextChunk(chunkData) {
     metadata: chunkData.metadata ?? {}
   };
 }
+function buildImageChunk(chunkData, filePath, imageBuffer) {
+  return {
+    chunkId: chunkData.chunkId ?? "",
+    type: "image",
+    content: chunkData.content ?? "",
+    path: chunkData.path ?? "",
+    filePath,
+    data: imageBuffer,
+    metadata: chunkData.metadata ?? {},
+    get format() {
+      return getFileExtension(this.filePath);
+    },
+    async save(directory) {
+      return writeBinaryAsset(directory, this.filePath, this.data);
+    }
+  };
+}
+function buildTableChunk(chunkData, filePath, html) {
+  return {
+    chunkId: chunkData.chunkId ?? "",
+    type: "table",
+    content: chunkData.content ?? "",
+    path: chunkData.path ?? "",
+    filePath,
+    html,
+    metadata: chunkData.metadata ?? {},
+    async save(directory) {
+      return writeTextAsset(directory, this.filePath, this.html);
+    }
+  };
+}
 async function processChunk(zip, chunkData) {
   if (chunkData.type === "text") {
     return buildTextChunk(chunkData);
@@ -1000,26 +1195,7 @@ async function processChunk(zip, chunkData) {
       throw new KnowhereError(`Image file not found: ${filePath}`);
     }
     const imageBuffer = await imageFile.async("nodebuffer");
-    const enrichedChunk = {
-      chunkId: chunkData.chunkId ?? "",
-      type: "image",
-      content: chunkData.content ?? "",
-      path: chunkData.path ?? "",
-      filePath,
-      data: imageBuffer,
-      metadata: chunkData.metadata ?? {},
-      get format() {
-        return getFileExtension(this.filePath);
-      },
-      async save(directory) {
-        const outputPath = (0, import_path.join)(directory, sanitizePath(this.filePath));
-        const outputDir = (0, import_path.dirname)(outputPath);
-        await import_fs2.promises.mkdir(outputDir, { recursive: true });
-        await import_fs2.promises.writeFile(outputPath, this.data);
-        return outputPath;
-      }
-    };
-    return enrichedChunk;
+    return buildImageChunk(chunkData, filePath, imageBuffer);
   }
   if (chunkData.type === "table") {
     const filePath = getChunkFilePath(chunkData);
@@ -1032,26 +1208,112 @@ async function processChunk(zip, chunkData) {
       throw new KnowhereError(`Table file not found: ${filePath}`);
     }
     const html = await htmlFile.async("string");
-    const enrichedChunk = {
-      chunkId: chunkData.chunkId ?? "",
-      type: "table",
-      content: chunkData.content ?? "",
-      path: chunkData.path ?? "",
-      filePath,
-      html,
-      metadata: chunkData.metadata ?? {},
-      async save(directory) {
-        const outputPath = (0, import_path.join)(directory, sanitizePath(this.filePath));
-        const outputDir = (0, import_path.dirname)(outputPath);
-        await import_fs2.promises.mkdir(outputDir, { recursive: true });
-        await import_fs2.promises.writeFile(outputPath, this.html);
-        return outputPath;
+    return buildTableChunk(chunkData, filePath, html);
+  }
+  return buildTextChunk(chunkData);
+}
+async function processDirectoryChunk(directory, chunkData) {
+  if (chunkData.type === "text") {
+    return buildTextChunk(chunkData);
+  }
+  if (chunkData.type === "image") {
+    const filePath = getChunkFilePath(chunkData);
+    if (!filePath) {
+      throw new KnowhereError(`Image chunk missing file path: ${chunkData.chunkId ?? "unknown"}`);
+    }
+    try {
+      const imageBuffer = await import_fs2.promises.readFile(resolveAssetPath(directory, filePath));
+      return buildImageChunk(chunkData, filePath, imageBuffer);
+    } catch (error) {
+      if (isMissingFileError(error)) {
+        throw new KnowhereError(`Image file not found: ${filePath}`);
       }
-    };
-    return enrichedChunk;
+      throw error;
+    }
+  }
+  if (chunkData.type === "table") {
+    const filePath = getChunkFilePath(chunkData);
+    if (!filePath) {
+      throw new KnowhereError(`Table chunk missing file path: ${chunkData.chunkId ?? "unknown"}`);
+    }
+    try {
+      const html = await import_fs2.promises.readFile(resolveAssetPath(directory, filePath), "utf8");
+      return buildTableChunk(chunkData, filePath, html);
+    } catch (error) {
+      if (isMissingFileError(error)) {
+        throw new KnowhereError(`Table file not found: ${filePath}`);
+      }
+      throw error;
+    }
   }
   return buildTextChunk(chunkData);
 }
+function serializeChunks(chunks) {
+  return {
+    chunks: chunks.map((chunk) => {
+      const rawChunk = {
+        chunkId: chunk.chunkId,
+        type: chunk.type,
+        content: chunk.content,
+        path: chunk.path,
+        metadata: chunk.metadata
+      };
+      if (chunk.type === "image" || chunk.type === "table") {
+        rawChunk.filePath = chunk.filePath;
+      }
+      return rawChunk;
+    })
+  };
+}
+async function readRequiredTextFile(directory, fileName) {
+  try {
+    return await import_fs2.promises.readFile((0, import_path.join)(directory, fileName), "utf8");
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      throw new KnowhereError(`${fileName} not found in result directory`);
+    }
+    throw error;
+  }
+}
+async function readOptionalTextFile(directory, fileName) {
+  try {
+    return await import_fs2.promises.readFile((0, import_path.join)(directory, fileName), "utf8");
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return void 0;
+    }
+    throw error;
+  }
+}
+async function readOptionalJsonFile(directory, fileName) {
+  const content = await readOptionalTextFile(directory, fileName);
+  return content === void 0 ? void 0 : JSON.parse(content);
+}
+async function writeBinaryAsset(directory, filePath, data) {
+  const outputPath = resolveAssetPath(directory, filePath);
+  const outputDir = (0, import_path.dirname)(outputPath);
+  await import_fs2.promises.mkdir(outputDir, { recursive: true });
+  await import_fs2.promises.writeFile(outputPath, data);
+  return outputPath;
+}
+async function writeTextAsset(directory, filePath, text) {
+  const outputPath = resolveAssetPath(directory, filePath);
+  const outputDir = (0, import_path.dirname)(outputPath);
+  await import_fs2.promises.mkdir(outputDir, { recursive: true });
+  await import_fs2.promises.writeFile(outputPath, text);
+  return outputPath;
+}
+function resolveAssetPath(directory, filePath) {
+  const root = (0, import_path.resolve)(directory);
+  const outputPath = (0, import_path.resolve)(root, sanitizePath(filePath));
+  if (outputPath !== root && !outputPath.startsWith(`${root}${import_path.sep}`)) {
+    throw new KnowhereError(`Invalid result asset path: ${filePath}`);
+  }
+  return outputPath;
+}
+function isMissingFileError(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
 
 // src/resources/jobs.ts
 var Jobs = class extends BaseResource {
@@ -1060,11 +1322,7 @@ var Jobs = class extends BaseResource {
    * Create a new parsing job
    */
   async create(params) {
-    const job = await this.httpClient.post(
-      "/v1/jobs",
-      params
-    );
-    delete job.documentId;
+    const job = await this.httpClient.post("/v1/jobs", params);
     if (job.uploadUrl) {
       this.pendingUploadJobs.set(job.jobId, job);
     }
@@ -1248,22 +1506,741 @@ var Documents = class extends BaseResource {
   }
 };
 
+// src/knowledge/local-store.ts
+var import_crypto = require("crypto");
+var import_os = __toESM(require("os"));
+var import_fs3 = require("fs");
+var import_path2 = __toESM(require("path"));
+var STORE_VERSION = 1;
+var LOCAL_DOCUMENT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+var LocalKnowledgeStore = class {
+  cacheDirectory;
+  indexPath;
+  resultCache = /* @__PURE__ */ new Map();
+  constructor(cacheDirectory) {
+    this.cacheDirectory = cacheDirectory ?? import_path2.default.join(import_os.default.homedir(), ".knowhere-node-sdk", "knowledge");
+    this.indexPath = import_path2.default.join(this.cacheDirectory, "index.json");
+  }
+  async saveResult(result, options) {
+    await import_fs3.promises.mkdir(this.cacheDirectory, { recursive: true });
+    const now = /* @__PURE__ */ new Date();
+    const index = await this.readIndex();
+    const localDocumentId = validateLocalDocumentId(
+      options?.localDocumentId ?? createLocalDocumentId(result)
+    );
+    const resultDirectoryPath = this.getResultDirectoryPath(localDocumentId);
+    await import_fs3.promises.rm(resultDirectoryPath, { recursive: true, force: true });
+    await saveExpandedParseResult(result, resultDirectoryPath);
+    this.resultCache.set(localDocumentId, result);
+    const existing = index.documents.find(
+      (document) => document.localDocumentId === localDocumentId
+    );
+    const stored = {
+      localDocumentId,
+      jobId: result.jobId,
+      documentId: result.documentId,
+      namespace: result.namespace,
+      sourceFileName: result.manifest.sourceFileName,
+      chunkCount: result.chunks.length,
+      typeCounts: countChunkTypes(result),
+      resultDirectoryPath,
+      createdAt: existing?.createdAt ?? now.toISOString(),
+      updatedAt: now.toISOString()
+    };
+    const nextDocuments = [
+      stored,
+      ...index.documents.filter((document) => document.localDocumentId !== localDocumentId)
+    ];
+    const asyncParseJobs = (index.asyncParseJobs ?? []).map(
+      (job) => job.jobId === result.jobId ? {
+        ...job,
+        localDocumentId,
+        cacheStatus: "cached",
+        updatedAt: now.toISOString()
+      } : job
+    );
+    await this.writeIndex({
+      version: STORE_VERSION,
+      documents: nextDocuments,
+      asyncParseJobs
+    });
+    return toLocalKnowledgeDocument(stored);
+  }
+  async saveAsyncParseJob(params) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const index = await this.readIndex();
+    const localDocumentId = params.localDocumentId ? validateLocalDocumentId(params.localDocumentId) : void 0;
+    const existing = (index.asyncParseJobs ?? []).find((job) => job.jobId === params.jobId);
+    const stored = {
+      jobId: params.jobId,
+      localDocumentId: localDocumentId ?? existing?.localDocumentId,
+      cacheStatus: existing?.cacheStatus ?? "pending",
+      createdAt: existing?.createdAt ?? now,
+      updatedAt: now
+    };
+    await this.writeIndex({
+      version: STORE_VERSION,
+      documents: index.documents,
+      asyncParseJobs: [
+        stored,
+        ...(index.asyncParseJobs ?? []).filter((job) => job.jobId !== params.jobId)
+      ]
+    });
+  }
+  async getAsyncParseJob(jobId) {
+    const index = await this.readIndex();
+    return (index.asyncParseJobs ?? []).find((job) => job.jobId === jobId);
+  }
+  async listRecoverableAsyncParseJobs() {
+    const index = await this.readIndex();
+    return (index.asyncParseJobs ?? []).filter((job) => job.cacheStatus === "pending" || job.cacheStatus === "not_available").map(toLocalKnowledgeAsyncParseJob);
+  }
+  async updateAsyncParseJobCacheStatus(params) {
+    const index = await this.readIndex();
+    const localDocumentId = params.localDocumentId ? validateLocalDocumentId(params.localDocumentId) : void 0;
+    const existing = (index.asyncParseJobs ?? []).find((job) => job.jobId === params.jobId);
+    if (!existing) {
+      return;
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const stored = {
+      ...existing,
+      localDocumentId: localDocumentId ?? existing.localDocumentId,
+      cacheStatus: params.cacheStatus,
+      updatedAt: now
+    };
+    await this.writeIndex({
+      version: STORE_VERSION,
+      documents: index.documents,
+      asyncParseJobs: [
+        stored,
+        ...(index.asyncParseJobs ?? []).filter((job) => job.jobId !== params.jobId)
+      ]
+    });
+  }
+  async listDocuments() {
+    const index = await this.readIndex();
+    return index.documents.map(toLocalKnowledgeDocument);
+  }
+  async getDocument(localDocumentId) {
+    validateLocalDocumentId(localDocumentId);
+    const index = await this.readIndex();
+    const stored = index.documents.find((document) => document.localDocumentId === localDocumentId);
+    return stored ? toLocalKnowledgeDocument(stored) : void 0;
+  }
+  async loadResult(localDocumentId) {
+    const document = await this.getDocument(localDocumentId);
+    if (!document) {
+      throw new Error(`Local Knowhere document not found: ${localDocumentId}`);
+    }
+    const cachedResult = this.resultCache.get(localDocumentId);
+    if (cachedResult) {
+      return { document, result: cachedResult };
+    }
+    const result = await this.loadStoredResult(document);
+    result.namespace = document.namespace;
+    result.documentId = document.documentId;
+    this.resultCache.set(localDocumentId, result);
+    return { document, result };
+  }
+  getResultDirectoryPath(localDocumentId) {
+    const documentsDirectory = import_path2.default.resolve(this.cacheDirectory, "documents");
+    const resultDirectoryPath = import_path2.default.resolve(documentsDirectory, localDocumentId);
+    if (!isPathInsideDirectory(resultDirectoryPath, documentsDirectory)) {
+      throw new Error(`Local Knowhere document ID resolves outside the cache: ${localDocumentId}`);
+    }
+    return resultDirectoryPath;
+  }
+  async loadStoredResult(document) {
+    return parseResultDirectory(document.resultDirectoryPath);
+  }
+  async readIndex() {
+    try {
+      const raw = await import_fs3.promises.readFile(this.indexPath, "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed.version !== STORE_VERSION || !Array.isArray(parsed.documents)) {
+        return { version: STORE_VERSION, documents: [], asyncParseJobs: [] };
+      }
+      return {
+        version: STORE_VERSION,
+        documents: parsed.documents,
+        asyncParseJobs: Array.isArray(parsed.asyncParseJobs) ? parsed.asyncParseJobs : []
+      };
+    } catch (error) {
+      if (isMissingFileError2(error)) {
+        return { version: STORE_VERSION, documents: [], asyncParseJobs: [] };
+      }
+      throw error;
+    }
+  }
+  async writeIndex(index) {
+    await import_fs3.promises.mkdir(this.cacheDirectory, { recursive: true });
+    await import_fs3.promises.writeFile(this.indexPath, JSON.stringify(index, null, 2));
+  }
+};
+function validateLocalDocumentId(localDocumentId) {
+  if (!LOCAL_DOCUMENT_ID_PATTERN.test(localDocumentId) || localDocumentId.includes("..") || import_path2.default.basename(localDocumentId) !== localDocumentId) {
+    throw new Error(
+      "Local Knowhere document ID must be a safe slug containing only letters, numbers, dots, underscores, or hyphens"
+    );
+  }
+  return localDocumentId;
+}
+function isPathInsideDirectory(targetPath, parentDirectory) {
+  const relativePath = import_path2.default.relative(parentDirectory, targetPath);
+  return relativePath.length === 0 || !relativePath.startsWith("..") && !import_path2.default.isAbsolute(relativePath);
+}
+function createLocalDocumentId(result) {
+  const hash = (0, import_crypto.createHash)("sha256").update(result.jobId).update("\0").update(result.manifest.sourceFileName).digest("hex").slice(0, 16);
+  return `local_${hash}`;
+}
+function countChunkTypes(result) {
+  return result.chunks.reduce(
+    (counts, chunk) => {
+      counts[chunk.type] += 1;
+      return counts;
+    },
+    { text: 0, image: 0, table: 0 }
+  );
+}
+function toLocalKnowledgeDocument(stored) {
+  return {
+    localDocumentId: stored.localDocumentId,
+    jobId: stored.jobId,
+    documentId: stored.documentId,
+    namespace: stored.namespace,
+    sourceFileName: stored.sourceFileName,
+    chunkCount: stored.chunkCount,
+    typeCounts: stored.typeCounts,
+    resultDirectoryPath: stored.resultDirectoryPath,
+    createdAt: new Date(stored.createdAt),
+    updatedAt: new Date(stored.updatedAt)
+  };
+}
+function toLocalKnowledgeAsyncParseJob(stored) {
+  return {
+    ...stored,
+    createdAt: new Date(stored.createdAt),
+    updatedAt: new Date(stored.updatedAt)
+  };
+}
+function isMissingFileError2(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+
+// src/knowledge/knowledge.ts
+var DEFAULT_READ_LIMIT = 12;
+var MAX_READ_LIMIT = 40;
+var DEFAULT_GREP_LIMIT = 20;
+var MAX_GREP_LIMIT = 50;
+var DEFAULT_CONTEXT_CHARS = 80;
+var Knowledge = class _Knowledge {
+  client;
+  store;
+  constructor(client, options) {
+    this.client = client;
+    this.store = new LocalKnowledgeStore(options?.cacheDirectory);
+  }
+  withCacheDirectory(cacheDirectory) {
+    return new _Knowledge(this.client, { cacheDirectory });
+  }
+  async parse(params) {
+    const result = await this.client.parse(params);
+    const document = await this.store.saveResult(result, {
+      localDocumentId: params.localDocumentId
+    });
+    return { document, result };
+  }
+  async startParse(params) {
+    const job = await this.client.startParse(params);
+    await this.store.saveAsyncParseJob({
+      jobId: job.jobId,
+      localDocumentId: params.localDocumentId
+    });
+    return {
+      job,
+      localDocumentId: params.localDocumentId
+    };
+  }
+  async getJobStatus(jobId) {
+    const job = await this.client.jobs.get(jobId);
+    return {
+      job,
+      cache: await this.resolveAsyncCache(jobId, job.isDone, job.isFailed)
+    };
+  }
+  async recoverPendingAsyncParseJobs() {
+    const jobs = await this.store.listRecoverableAsyncParseJobs();
+    const results = [];
+    for (const job of jobs) {
+      results.push(await this.getJobStatus(job.jobId));
+    }
+    return {
+      checkedJobs: jobs.length,
+      results
+    };
+  }
+  async cacheJobResult(params) {
+    const result = await this.client.jobs.load(params.jobId, {
+      verifyChecksum: params.verifyChecksum
+    });
+    const document = await this.store.saveResult(result, {
+      localDocumentId: params.localDocumentId
+    });
+    return { document, result };
+  }
+  async resolveAsyncCache(jobId, isDone, isFailed) {
+    const trackedJob = await this.store.getAsyncParseJob(jobId);
+    if (!trackedJob) {
+      return { status: "untracked" };
+    }
+    if (trackedJob.cacheStatus === "cached" && trackedJob.localDocumentId) {
+      const existingDocument = await this.store.getDocument(trackedJob.localDocumentId);
+      if (existingDocument) {
+        return {
+          status: "already_cached",
+          localDocumentId: trackedJob.localDocumentId,
+          document: existingDocument
+        };
+      }
+    }
+    if (isFailed) {
+      await this.store.updateAsyncParseJobCacheStatus({
+        jobId,
+        cacheStatus: "failed"
+      });
+      return {
+        status: "failed",
+        localDocumentId: trackedJob.localDocumentId
+      };
+    }
+    if (!isDone) {
+      return {
+        status: "pending",
+        localDocumentId: trackedJob.localDocumentId
+      };
+    }
+    try {
+      const cached = await this.cacheJobResult({
+        jobId,
+        localDocumentId: trackedJob.localDocumentId
+      });
+      return {
+        status: "cached",
+        localDocumentId: cached.document.localDocumentId,
+        document: cached.document
+      };
+    } catch (error) {
+      await this.store.updateAsyncParseJobCacheStatus({
+        jobId,
+        cacheStatus: "not_available"
+      });
+      return {
+        status: "not_available",
+        localDocumentId: trackedJob.localDocumentId,
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
+  async listDocuments() {
+    return this.store.listDocuments();
+  }
+  async getDocumentOutline(localDocumentId) {
+    const { document, result } = await this.store.loadResult(localDocumentId);
+    const chunks = indexChunks(result);
+    const sections = buildFlatSections(result, chunks);
+    const sectionTree = result.docNav?.sections && result.docNav.sections.length > 0 ? result.docNav.sections.map(
+      (section) => toKnowledgeSection(section, chunks, result.manifest.sourceFileName)
+    ) : nestSections(sections);
+    return {
+      document,
+      totalChunks: chunks.length,
+      typeCounts: document.typeCounts,
+      sections,
+      sectionTree
+    };
+  }
+  async readChunks(params) {
+    const { document, result } = await this.store.loadResult(params.localDocumentId);
+    const limit = clampLimit(params.limit, DEFAULT_READ_LIMIT, MAX_READ_LIMIT);
+    const chunks = indexChunks(result).filter((chunk) => matchesReadScope(chunk, params));
+    const selected = selectReadWindow(chunks, params, limit);
+    const lastSelected = selected[selected.length - 1];
+    const nextChunk = lastSelected && selected.length < chunks.length ? chunks[chunks.indexOf(lastSelected) + 1]?.position : void 0;
+    return {
+      document,
+      chunks: selected.map(toReadChunk),
+      nextChunk
+    };
+  }
+  async grepChunks(params) {
+    if (!params.pattern) {
+      throw new ValidationError("pattern is required");
+    }
+    const { document, result } = await this.store.loadResult(params.localDocumentId);
+    const maxResults = clampLimit(params.maxResults, DEFAULT_GREP_LIMIT, MAX_GREP_LIMIT);
+    const contextChars = params.contextChars ?? DEFAULT_CONTEXT_CHARS;
+    const matcher = createMatcher(params);
+    const scopedChunks = indexChunks(result).filter((chunk) => matchesGrepScope(chunk, params));
+    const matches = [];
+    let scannedChunks = 0;
+    for (const chunk of scopedChunks) {
+      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)
+        });
+        if (matches.length >= maxResults) {
+          return { document, matches, scannedChunks, truncated: true };
+        }
+      }
+    }
+    return { document, matches, scannedChunks, truncated: false };
+  }
+  async search(params) {
+    const localDocuments = await this.resolveSearchDocuments(params.localDocumentIds);
+    const rawResponse = await this.client.retrieval.query({
+      query: params.query,
+      namespace: params.namespace,
+      topK: params.topK,
+      useAgentic: params.useAgentic ?? false
+    });
+    const documentByServerId = new Map(
+      localDocuments.filter((document) => document.documentId).map((document) => [document.documentId, document])
+    );
+    return {
+      namespace: rawResponse.namespace,
+      query: rawResponse.query,
+      evidenceText: rawResponse.evidenceText,
+      references: [
+        ...rawResponse.referencedChunks.map(
+          (reference) => ({
+            localDocumentId: reference.documentId ? documentByServerId.get(reference.documentId)?.localDocumentId : void 0,
+            documentId: reference.documentId,
+            chunkId: reference.chunkId,
+            sectionPath: reference.sectionPath,
+            chunkType: reference.chunkType
+          })
+        ),
+        ...rawResponse.results.map((result) => toResultReference(result, documentByServerId))
+      ],
+      results: rawResponse.results.map(
+        (result) => toRemoteSearchResult(result, documentByServerId)
+      ),
+      rawResponse
+    };
+  }
+  async resolveSearchDocuments(localDocumentIds) {
+    const documents = await this.store.listDocuments();
+    if (!localDocumentIds || localDocumentIds.length === 0) {
+      return documents;
+    }
+    const requested = new Set(localDocumentIds);
+    return documents.filter((document) => requested.has(document.localDocumentId));
+  }
+};
+function indexChunks(result) {
+  return result.chunks.map((chunk, index) => {
+    const filePath = getChunkFilePath2(chunk);
+    return {
+      source: chunk,
+      position: index + 1,
+      chunkId: chunk.chunkId,
+      chunkType: chunk.type,
+      content: chunk.content,
+      sectionPath: normalizeSectionPath(chunk.path, result.manifest.sourceFileName),
+      sourceChunkPath: chunk.path,
+      filePath,
+      metadata: chunk.metadata
+    };
+  });
+}
+function getChunkFilePath2(chunk) {
+  if (chunk.type === "image" || chunk.type === "table") {
+    return chunk.filePath;
+  }
+  const filePath = chunk.metadata.filePath;
+  return typeof filePath === "string" ? filePath : void 0;
+}
+function normalizeSectionPath(path3, sourceFileName) {
+  if (!path3) {
+    return "";
+  }
+  if (path3.startsWith("images/") || path3.startsWith("tables/")) {
+    return path3;
+  }
+  const parts = path3.split("/").filter(Boolean);
+  if (sourceFileName) {
+    const fileNameIndex = parts.indexOf(sourceFileName);
+    if (fileNameIndex >= 0) {
+      return parts.slice(fileNameIndex + 1).join(" / ") || sourceFileName;
+    }
+  }
+  if (parts.length <= 1) {
+    return parts[0] ?? "";
+  }
+  return parts.slice(1).join(" / ");
+}
+function buildFlatSections(result, chunks) {
+  if (result.docNav?.sections && result.docNav.sections.length > 0) {
+    return flattenSections(
+      result.docNav.sections.map(
+        (section) => toKnowledgeSection(section, chunks, result.manifest.sourceFileName)
+      )
+    );
+  }
+  const byPath = /* @__PURE__ */ new Map();
+  for (const chunk of chunks) {
+    const path3 = chunk.sectionPath || chunk.sourceChunkPath;
+    const existing = byPath.get(path3);
+    if (existing) {
+      addChunkToSection(existing, chunk);
+    } else {
+      byPath.set(path3, createSectionFromChunk(path3, chunk));
+    }
+  }
+  return [...byPath.values()].sort(compareSections);
+}
+function toKnowledgeSection(section, chunks, sourceFileName) {
+  const sectionPath = normalizeSectionPath(section.path, sourceFileName);
+  const scopedChunks = chunks.filter((chunk) => isInSection(chunk.sectionPath, sectionPath));
+  const children = section.children.map(
+    (child) => toKnowledgeSection(child, chunks, sourceFileName)
+  );
+  return {
+    sectionPath,
+    sectionTitle: section.title,
+    sectionLevel: section.level,
+    summary: section.summary,
+    startChunk: minPosition(scopedChunks),
+    endChunk: maxPosition(scopedChunks),
+    chunkCount: scopedChunks.length,
+    typeCounts: countIndexedTypes(scopedChunks),
+    children
+  };
+}
+function createSectionFromChunk(pathValue, chunk) {
+  const parts = pathValue.split(" / ").filter(Boolean);
+  return {
+    sectionPath: pathValue,
+    sectionTitle: parts[parts.length - 1] ?? pathValue,
+    sectionLevel: Math.max(parts.length, 1),
+    startChunk: chunk.position,
+    endChunk: chunk.position,
+    chunkCount: 1,
+    typeCounts: { text: 0, image: 0, table: 0, [chunk.chunkType]: 1 },
+    children: []
+  };
+}
+function addChunkToSection(section, chunk) {
+  section.startChunk = Math.min(section.startChunk ?? chunk.position, chunk.position);
+  section.endChunk = Math.max(section.endChunk ?? chunk.position, chunk.position);
+  section.chunkCount += 1;
+  section.typeCounts[chunk.chunkType] += 1;
+}
+function flattenSections(sections) {
+  return sections.flatMap((section) => [section, ...flattenSections(section.children)]);
+}
+function nestSections(sections) {
+  const clonedSections = sections.map((section) => ({
+    ...section,
+    children: []
+  }));
+  const byPath = new Map(clonedSections.map((section) => [section.sectionPath, section]));
+  const roots = [];
+  for (const section of clonedSections) {
+    const parentPath = getParentSectionPath(section.sectionPath);
+    const parent = parentPath ? byPath.get(parentPath) : void 0;
+    if (parent) {
+      parent.children.push(section);
+    } else {
+      roots.push(section);
+    }
+  }
+  return roots;
+}
+function getParentSectionPath(sectionPath) {
+  const parts = sectionPath.split(" / ").filter(Boolean);
+  if (parts.length <= 1) {
+    return void 0;
+  }
+  return parts.slice(0, -1).join(" / ");
+}
+function compareSections(left, right) {
+  return (left.startChunk ?? Number.MAX_SAFE_INTEGER) - (right.startChunk ?? Number.MAX_SAFE_INTEGER);
+}
+function minPosition(chunks) {
+  if (chunks.length === 0) {
+    return void 0;
+  }
+  return Math.min(...chunks.map((chunk) => chunk.position));
+}
+function maxPosition(chunks) {
+  if (chunks.length === 0) {
+    return void 0;
+  }
+  return Math.max(...chunks.map((chunk) => chunk.position));
+}
+function countIndexedTypes(chunks) {
+  return chunks.reduce(
+    (counts, chunk) => {
+      counts[chunk.chunkType] += 1;
+      return counts;
+    },
+    { text: 0, image: 0, table: 0 }
+  );
+}
+function isInSection(chunkSectionPath, sectionPath) {
+  return chunkSectionPath === sectionPath || chunkSectionPath.startsWith(`${sectionPath} / `);
+}
+function clampLimit(value, defaultValue, maxValue) {
+  if (value === void 0) {
+    return defaultValue;
+  }
+  return Math.min(Math.max(Math.floor(value), 1), maxValue);
+}
+function matchesReadScope(chunk, params) {
+  if (params.chunkId && chunk.chunkId !== params.chunkId) {
+    return false;
+  }
+  if (params.chunkType && chunk.chunkType !== params.chunkType) {
+    return false;
+  }
+  if (params.sectionPath && !isInSection(chunk.sectionPath, params.sectionPath)) {
+    return false;
+  }
+  return true;
+}
+function selectReadWindow(chunks, params, limit) {
+  if (params.chunkId) {
+    return chunks.slice(0, limit);
+  }
+  const startChunk = params.startChunk ?? chunks[0]?.position ?? 1;
+  const endChunk = params.endChunk ?? Number.MAX_SAFE_INTEGER;
+  return chunks.filter((chunk) => chunk.position >= startChunk && chunk.position <= endChunk).slice(0, limit);
+}
+function toReadChunk(chunk) {
+  return {
+    position: chunk.position,
+    chunkId: chunk.chunkId,
+    chunkType: chunk.chunkType,
+    content: chunk.content,
+    sectionPath: chunk.sectionPath,
+    sourceChunkPath: chunk.sourceChunkPath,
+    filePath: chunk.filePath,
+    metadata: chunk.metadata
+  };
+}
+function matchesGrepScope(chunk, params) {
+  if (params.chunkType && chunk.chunkType !== params.chunkType) {
+    return false;
+  }
+  if (params.sectionPathPrefix && !chunk.sectionPath.startsWith(params.sectionPathPrefix)) {
+    return false;
+  }
+  return true;
+}
+function createMatcher(params) {
+  if (params.isRegex) {
+    const flags = params.isCaseSensitive ? "g" : "gi";
+    const regex = new RegExp(params.pattern, flags);
+    return (content) => {
+      const matches = [];
+      for (const match of content.matchAll(regex)) {
+        const startOffset = match.index ?? 0;
+        const text = match[0] ?? "";
+        matches.push({ startOffset, endOffset: startOffset + text.length });
+        if (text.length === 0) {
+          break;
+        }
+      }
+      return matches;
+    };
+  }
+  const needle = params.isCaseSensitive ? params.pattern : params.pattern.toLowerCase();
+  return (content) => {
+    const haystack = params.isCaseSensitive ? content : content.toLowerCase();
+    const matches = [];
+    let index = haystack.indexOf(needle);
+    while (index >= 0) {
+      matches.push({ startOffset: index, endOffset: index + needle.length });
+      index = haystack.indexOf(needle, index + Math.max(needle.length, 1));
+    }
+    return matches;
+  };
+}
+function buildSnippet(content, startOffset, endOffset, contextChars) {
+  const start = Math.max(0, startOffset - contextChars);
+  const end = Math.min(content.length, endOffset + contextChars);
+  return content.slice(start, end);
+}
+function toResultReference(result, documentByServerId) {
+  const documentId = result.source.documentId ?? void 0;
+  return {
+    localDocumentId: documentId ? documentByServerId.get(documentId)?.localDocumentId : void 0,
+    documentId,
+    sectionPath: result.source.sectionPath ?? void 0,
+    chunkType: result.chunkType,
+    score: result.score
+  };
+}
+function toRemoteSearchResult(result, documentByServerId) {
+  const documentId = result.source.documentId ?? void 0;
+  return {
+    localDocumentId: documentId ? documentByServerId.get(documentId)?.localDocumentId : void 0,
+    documentId,
+    chunkType: result.chunkType,
+    content: result.content,
+    score: result.score,
+    sectionPath: result.source.sectionPath ?? void 0,
+    sourceFileName: result.source.sourceFileName ?? void 0
+  };
+}
+
 // src/client.ts
 function inferFileName(file, explicitFileName) {
   if (explicitFileName) {
     return explicitFileName;
   }
   if (typeof file === "string") {
-    return import_path2.default.basename(file);
+    return import_path3.default.basename(file);
   }
   if (isReadStream2(file) && typeof file.path === "string") {
-    return import_path2.default.basename(file.path);
+    return import_path3.default.basename(file.path);
   }
   return void 0;
 }
 function isReadStream2(file) {
   return typeof file === "object" && file !== null && "pipe" in file && typeof file.pipe === "function";
 }
+function buildParsingParams(params) {
+  const parsingParams = {
+    model: params.model,
+    ocrEnabled: params.ocr,
+    docType: params.docType,
+    smartTitleParse: params.smartTitleParse,
+    summaryImage: params.summaryImage,
+    summaryTable: params.summaryTable,
+    summaryTxt: params.summaryTxt,
+    addFragDesc: params.addFragDesc,
+    kbDir: params.kbDir
+  };
+  Object.keys(parsingParams).forEach((key) => {
+    if (parsingParams[key] === void 0) {
+      delete parsingParams[key];
+    }
+  });
+  return Object.keys(parsingParams).length > 0 ? parsingParams : void 0;
+}
 var Knowhere = class {
   /** Jobs resource for low-level API */
   jobs;
@@ -1271,21 +2248,25 @@ var Knowhere = class {
   retrieval;
   /** Documents resource for canonical document lifecycle operations */
   documents;
+  /** Client-side local knowledge tools over parsed Knowhere results */
+  knowledge;
   httpClient;
   /**
    * Create a new Knowhere client
    */
   constructor(options = {}) {
     const apiKey = options.apiKey ?? process.env[ENV.API_KEY];
-    if (!apiKey) {
+    const authTokenProvider = apiKey ? void 0 : options.authTokenProvider;
+    if (!apiKey && !authTokenProvider) {
       throw new ValidationError(
-        `API key is required. Provide it via options.apiKey or ${ENV.API_KEY} environment variable.`
+        `API authentication is required. Provide it via options.apiKey, options.authTokenProvider, or ${ENV.API_KEY} environment variable.`
       );
     }
     const baseURL = options.baseURL ?? process.env[ENV.BASE_URL] ?? DEFAULT_BASE_URL;
     this.httpClient = new HttpClient({
       baseURL,
       apiKey,
+      authTokenProvider,
       timeout: options.timeout,
       uploadTimeout: options.uploadTimeout,
       maxRetries: options.maxRetries,
@@ -1296,6 +2277,7 @@ var Knowhere = class {
     this.jobs = new Jobs(this.httpClient);
     this.retrieval = new Retrieval(this.httpClient);
     this.documents = new Documents(this.httpClient);
+    this.knowledge = new Knowledge(this);
   }
   /**
    * High-level API: Parse a document and return structured results
@@ -1318,6 +2300,24 @@ var Knowhere = class {
    * ```
    */
   async parse(params) {
+    const job = await this.startParse(params);
+    const jobResult = await this.jobs.wait(job.jobId, {
+      pollInterval: params.pollInterval,
+      pollTimeout: params.pollTimeout,
+      onProgress: params.onPollProgress,
+      signal: params.signal
+    });
+    const result = await this.jobs.load(jobResult, {
+      verifyChecksum: params.verifyChecksum
+    });
+    return enrichParseResult(result, jobResult);
+  }
+  /**
+   * Start a parse job and return immediately after the URL job is created or
+   * the local file is uploaded. Use jobs.get()/jobs.wait() and jobs.load()
+   * to inspect completion and load results later.
+   */
+  async startParse(params) {
     if (!params.url && !params.file) {
       throw new ValidationError("Either url or file must be provided");
     }
@@ -1331,22 +2331,6 @@ var Knowhere = class {
         "fileName is required when file is a Buffer, Uint8Array, or stream without a path."
       );
     }
-    const parsingParams = {
-      model: params.model,
-      ocrEnabled: params.ocr,
-      docType: params.docType,
-      smartTitleParse: params.smartTitleParse,
-      summaryImage: params.summaryImage,
-      summaryTable: params.summaryTable,
-      summaryTxt: params.summaryTxt,
-      addFragDesc: params.addFragDesc,
-      kbDir: params.kbDir
-    };
-    Object.keys(parsingParams).forEach((key) => {
-      if (parsingParams[key] === void 0) {
-        delete parsingParams[key];
-      }
-    });
     const webhook = params.webhook;
     const job = await this.jobs.create({
       sourceType,
@@ -1355,7 +2339,8 @@ var Knowhere = class {
       dataId: params.dataId,
       namespace: params.namespace,
       documentId: params.documentId,
-      parsingParams: Object.keys(parsingParams).length > 0 ? parsingParams : void 0,
+      documentMetadata: params.documentMetadata,
+      parsingParams: buildParsingParams(params),
       webhook
     });
     if (params.file) {
@@ -1365,16 +2350,7 @@ var Knowhere = class {
         signal: params.signal
       });
     }
-    const jobResult = await this.jobs.wait(job.jobId, {
-      pollInterval: params.pollInterval,
-      pollTimeout: params.pollTimeout,
-      onProgress: params.onPollProgress,
-      signal: params.signal
-    });
-    const result = await this.jobs.load(jobResult, {
-      verifyChecksum: params.verifyChecksum
-    });
-    return enrichParseResult(result, jobResult);
+    return job;
   }
 };
 // Annotate the CommonJS export names for ESM import in node:
@@ -1392,6 +2368,8 @@ var Knowhere = class {
   Jobs,
   Knowhere,
   KnowhereError,
+  Knowledge,
+  LocalKnowledgeStore,
   NetworkError,
   NotFoundError,
   PaymentRequiredError,