@ontos-ai/knowhere-sdk 0.5.0 → 0.7.0

package/README.md

@@ -196,8 +196,11 @@ const response = await client.retrieval.query({
   useAgentic: true,
 });
 
-console.log(response.answerText);         // LLM-generated answer
-console.log(response.referencedChunks);   // cited evidence chunks
+console.log(response.answerText); // LLM-generated answer
+console.log(response.referencedChunks); // cited evidence chunks
+console.log(response.evidenceText); // rendered evidence context, when returned
+console.log(response.stopReason); // agentic termination reason, when returned
+console.log(response.failureReason); // no-answer reason, when returned
 
 for (const result of response.results) {
   console.log(result.content);
@@ -218,6 +221,20 @@ result.source.sourceFileName;
 result.source.sectionPath;
 ```
 
+Agentic references expose the current retrieval citation fields:
+
+```typescript
+const reference = response.referencedChunks[0];
+
+reference.chunkId;
+reference.documentId;
+reference.chunkType;
+reference.sectionPath;
+reference.filePath;
+reference.jobId;
+reference.assetUrl;
+```
+
 Use `documentId` to update or archive a document:
 
 ```typescript
@@ -248,6 +265,72 @@ if (chunks.chunks[0]) {
 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.
+
+```typescript
+const parsed = await client.knowledge.parse({
+  file: './manual.pdf',
+  localDocumentId: 'manual-v1',
+});
+
+const outline = await client.knowledge.getDocumentOutline(parsed.document.localDocumentId);
+
+const read = await client.knowledge.readChunks({
+  localDocumentId: parsed.document.localDocumentId,
+  sectionPath: outline.sections[0]?.sectionPath,
+  limit: 5,
+});
+
+const grep = await client.knowledge.grepChunks({
+  localDocumentId: parsed.document.localDocumentId,
+  pattern: 'warranty',
+  maxResults: 10,
+});
+
+const serverSearch = await client.knowledge.search({
+  query: 'battery warranty',
+  localDocumentIds: [parsed.document.localDocumentId],
+  topK: 5,
+});
+
+console.log(read.chunks);
+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.
+The MCP package is a wrapper over this SDK interface; install it only when an
+agent host needs an MCP server. See the MCP package README for Codex, Claude
+Code, Claude Desktop, and generic stdio MCP host configuration examples.
+
+For longer parses, use the non-blocking SDK flow and cache the result after the
+job completes:
+
+```typescript
+const started = await client.knowledge.startParse({
+  file: './manual.pdf',
+  localDocumentId: 'manual-v1',
+});
+
+const status = await client.knowledge.getJobStatus(started.job.jobId);
+
+if (status.job.isDone && status.cache.document) {
+  console.log(status.cache.document.localDocumentId);
+}
+```
+
+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.
+
 Follow-up queries can exclude documents or sections for one request:
 
 ```typescript

package/dist/index.d.mts

@@ -3,12 +3,15 @@ import { Agent as Agent$1 } from 'https';
 import { ReadStream } from 'fs';
 import { AxiosRequestConfig, AxiosInstance } from 'axios';
 
+type AuthTokenProvider = () => string | Promise<string>;
 /**
  * Configuration options for the Knowhere client
  */
 interface KnowhereOptions {
     /** API authentication key (defaults to KNOWHERE_API_KEY env var) */
     apiKey?: string;
+    /** Dynamic bearer token provider for short-lived non-API-key auth flows */
+    authTokenProvider?: AuthTokenProvider;
     /** API base URL (defaults to https://api.knowhereto.ai) */
     baseURL?: string;
     /** Request timeout in milliseconds (default: 60000) */
@@ -520,7 +523,8 @@ interface ParseResult {
 
 interface HttpClientOptions {
     baseURL: string;
-    apiKey: string;
+    apiKey?: string;
+    authTokenProvider?: AuthTokenProvider;
     timeout?: number;
     uploadTimeout?: number;
     maxRetries?: number;
@@ -537,8 +541,10 @@ declare class HttpClient {
     private uploadTimeout;
     private httpAgent?;
     private httpsAgent?;
+    private authTokenProvider?;
     constructor(options: HttpClientOptions);
     private setupInterceptors;
+    private attachDynamicAuthorization;
     private handleError;
     private getErrorObject;
     private normalizeErrorData;
@@ -679,11 +685,11 @@ interface RetrievalQueryParams {
  */
 interface RetrievalSource {
     /** Stable document identifier */
-    documentId?: string;
+    documentId?: string | null;
     /** Original source file name */
-    sourceFileName?: string;
+    sourceFileName?: string | null;
     /** Human-readable section path */
-    sectionPath?: string;
+    sectionPath?: string | null;
 }
 /**
  * Canonical chunk result returned by retrieval query.
@@ -693,15 +699,39 @@ interface RetrievalResult {
     content: string;
     /** Chunk type, for example text, image, or table */
     chunkType: string;
-    /** Retrieval score returned by the API */
-    score: number;
+    /** Retrieval score returned by the API. Null when no score is available (agentic navigation-only results). */
+    score: number | null;
     /** Presigned asset URL for media chunks when available */
     assetUrl?: string;
     /** Source reference for this result */
     source: RetrievalSource;
 }
+/**
+ * Cited evidence chunk returned by agentic retrieval.
+ */
+interface RetrievalReferencedChunk {
+    /** Parser-provided chunk identifier */
+    chunkId: string;
+    /** Stable document identifier */
+    documentId: string;
+    /** Chunk type, for example text, image, or table */
+    chunkType: string;
+    /** Human-readable section path */
+    sectionPath: string;
+    /** Generated artifact file path for media chunks */
+    filePath?: string | null;
+    /** Published job identifier for the referenced chunk */
+    jobId?: string | null;
+    /** Presigned asset URL for media chunks when available */
+    assetUrl?: string | null;
+}
 /**
  * Response from POST /v1/retrieval/query.
+ *
+ * Three PRIMARY output fields for downstream agent consumption:
+ * - `evidenceText`: hierarchical evidence tree for LLM context
+ * - `decisionTrace`: per-step navigation decisions (includes stop/failure)
+ * - `referencedChunks`: structured chunk citations for follow-up queries
  */
 interface RetrievalQueryResponse {
     /** Namespace searched by the API */
@@ -709,11 +739,19 @@ interface RetrievalQueryResponse {
     /** Echoed query text */
     query: string;
     /** Retrieval router path used by the API for this query */
-    routerUsed?: string;
-    /** LLM-generated natural-language answer (agentic mode only) */
-    answerText?: string | null;
-    /** Cited evidence chunks with asset URLs (agentic mode only) */
-    referencedChunks?: Array<Record<string, unknown>> | null;
+    routerUsed: string;
+    /** LLM-generated natural-language answer, or null when no answer was produced */
+    answerText: string | null;
+    /** Cited evidence chunks with asset URLs when available */
+    referencedChunks: RetrievalReferencedChunk[];
+    /** Tree-structured evidence text rendered by the agentic navigator */
+    evidenceText?: string | null;
+    /** Reason why the agentic run stopped (e.g. answer_done, not_found) */
+    stopReason?: string | null;
+    /** Semantic failure reason when the agentic evidence is insufficient */
+    failureReason?: string | null;
+    /** Per-step navigation decisions from agentic retrieval, including terminal stop/failure */
+    decisionTrace?: Record<string, unknown>[];
     /** Ranked retrieval results */
     results: RetrievalResult[];
 }
@@ -887,6 +925,234 @@ declare class Documents extends BaseResource {
     private createChunkGetRequestConfig;
 }
 
+type KnowledgeChunkType = DocumentChunkType;
+interface KnowledgeParseParams extends ParseParams {
+    /** Optional stable local identifier for this parsed result copy. */
+    localDocumentId?: string;
+}
+interface LocalKnowledgeDocument {
+    /** Stable local identifier used by local outline/read/grep methods. */
+    localDocumentId: string;
+    /** Server parse job identifier. */
+    jobId: string;
+    /** Server canonical document identifier when publication returned one. */
+    documentId?: string;
+    /** Server retrieval namespace when available. */
+    namespace?: string;
+    /** Original source file name from the parse manifest. */
+    sourceFileName: string;
+    /** Number of chunks in the locally cached parse result. */
+    chunkCount: number;
+    /** Chunk counts grouped by type. */
+    typeCounts: Record<KnowledgeChunkType, number>;
+    /** Local cache directory containing expanded Knowhere result files and assets. */
+    resultDirectoryPath: string;
+    /** Cache creation time. */
+    createdAt: Date;
+    /** Last cache write time. */
+    updatedAt: Date;
+}
+interface LocalKnowledgeParseResponse {
+    document: LocalKnowledgeDocument;
+    result: ParseResult;
+}
+interface KnowledgeAsyncParseParams extends ParseParams {
+    /** Optional stable local identifier to use when this job result is cached later. */
+    localDocumentId?: string;
+}
+interface KnowledgeAsyncParseResponse {
+    job: Job;
+    localDocumentId?: string;
+}
+type KnowledgeAsyncCacheStatus = 'pending' | 'cached' | 'already_cached' | 'untracked' | 'not_available' | 'failed';
+interface KnowledgeAsyncCacheResult {
+    status: KnowledgeAsyncCacheStatus;
+    localDocumentId?: string;
+    document?: LocalKnowledgeDocument;
+    error?: string;
+}
+interface KnowledgeAsyncJobStatusResponse {
+    job: JobResult;
+    cache: KnowledgeAsyncCacheResult;
+}
+interface KnowledgeStartupRecoveryResponse {
+    checkedJobs: number;
+    results: KnowledgeAsyncJobStatusResponse[];
+}
+interface KnowledgeCacheJobResultParams {
+    jobId: string;
+    localDocumentId?: string;
+    verifyChecksum?: boolean;
+}
+interface KnowledgeSection {
+    sectionPath: string;
+    sectionTitle: string;
+    sectionLevel: number;
+    summary?: string;
+    startChunk?: number;
+    endChunk?: number;
+    chunkCount: number;
+    typeCounts: Record<KnowledgeChunkType, number>;
+    children: KnowledgeSection[];
+}
+interface KnowledgeOutline {
+    document: LocalKnowledgeDocument;
+    totalChunks: number;
+    typeCounts: Record<KnowledgeChunkType, number>;
+    sections: KnowledgeSection[];
+    sectionTree: KnowledgeSection[];
+}
+interface KnowledgeReadParams {
+    localDocumentId: string;
+    sectionPath?: string;
+    startChunk?: number;
+    endChunk?: number;
+    chunkId?: string;
+    chunkType?: KnowledgeChunkType;
+    limit?: number;
+}
+interface KnowledgeReadChunk {
+    position: number;
+    chunkId: string;
+    chunkType: KnowledgeChunkType;
+    content: string;
+    sectionPath: string;
+    sourceChunkPath: string;
+    filePath?: string;
+    metadata: Record<string, unknown>;
+}
+interface KnowledgeReadResponse {
+    document: LocalKnowledgeDocument;
+    chunks: KnowledgeReadChunk[];
+    nextChunk?: number;
+}
+interface KnowledgeGrepParams {
+    localDocumentId: string;
+    pattern: string;
+    isRegex?: boolean;
+    isCaseSensitive?: boolean;
+    maxResults?: number;
+    chunkType?: KnowledgeChunkType;
+    sectionPathPrefix?: string;
+    contextChars?: number;
+}
+interface KnowledgeGrepMatch {
+    position: number;
+    chunkId: string;
+    chunkType: KnowledgeChunkType;
+    sectionPath: string;
+    sourceChunkPath: string;
+    filePath?: string;
+    startOffset: number;
+    endOffset: number;
+    snippet: string;
+}
+interface KnowledgeGrepResponse {
+    document: LocalKnowledgeDocument;
+    matches: KnowledgeGrepMatch[];
+    scannedChunks: number;
+    truncated: boolean;
+}
+interface KnowledgeSearchParams {
+    query: string;
+    namespace?: string;
+    topK?: number;
+    localDocumentIds?: string[];
+    useAgentic?: boolean;
+}
+interface KnowledgeSearchReference {
+    localDocumentId?: string;
+    documentId?: string;
+    chunkId?: string;
+    sectionPath?: string;
+    chunkType?: string;
+    score?: number | null;
+}
+interface KnowledgeSearchResponse {
+    namespace?: string;
+    query: string;
+    evidenceText?: string | null;
+    references: KnowledgeSearchReference[];
+    results: KnowledgeSearchResult[];
+    rawResponse: unknown;
+}
+interface KnowledgeSearchResult {
+    localDocumentId?: string;
+    documentId?: string;
+    chunkId?: string;
+    chunkType?: string;
+    content: string;
+    score: number | null;
+    sectionPath?: string;
+    sourceFileName?: string;
+}
+
+declare class Knowledge {
+    private readonly client;
+    private readonly store;
+    constructor(client: Knowhere, options?: {
+        cacheDirectory?: string;
+    });
+    withCacheDirectory(cacheDirectory: string): Knowledge;
+    parse(params: KnowledgeParseParams): Promise<LocalKnowledgeParseResponse>;
+    startParse(params: KnowledgeAsyncParseParams): Promise<KnowledgeAsyncParseResponse>;
+    getJobStatus(jobId: string): Promise<KnowledgeAsyncJobStatusResponse>;
+    recoverPendingAsyncParseJobs(): Promise<KnowledgeStartupRecoveryResponse>;
+    cacheJobResult(params: KnowledgeCacheJobResultParams): Promise<LocalKnowledgeParseResponse>;
+    private resolveAsyncCache;
+    listDocuments(): Promise<LocalKnowledgeDocument[]>;
+    getDocumentOutline(localDocumentId: string): Promise<KnowledgeOutline>;
+    readChunks(params: KnowledgeReadParams): Promise<KnowledgeReadResponse>;
+    grepChunks(params: KnowledgeGrepParams): Promise<KnowledgeGrepResponse>;
+    search(params: KnowledgeSearchParams): Promise<KnowledgeSearchResponse>;
+    private resolveSearchDocuments;
+}
+
+interface StoredAsyncParseJob {
+    jobId: string;
+    localDocumentId?: string;
+    cacheStatus: KnowledgeAsyncCacheStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+interface LocalKnowledgeAsyncParseJob {
+    jobId: string;
+    localDocumentId?: string;
+    cacheStatus: KnowledgeAsyncCacheStatus;
+    createdAt: Date;
+    updatedAt: Date;
+}
+declare class LocalKnowledgeStore {
+    private readonly cacheDirectory;
+    private readonly indexPath;
+    private readonly resultCache;
+    constructor(cacheDirectory?: string);
+    saveResult(result: ParseResult, options?: {
+        localDocumentId?: string;
+    }): Promise<LocalKnowledgeDocument>;
+    saveAsyncParseJob(params: {
+        jobId: string;
+        localDocumentId?: string;
+    }): Promise<void>;
+    getAsyncParseJob(jobId: string): Promise<StoredAsyncParseJob | undefined>;
+    listRecoverableAsyncParseJobs(): Promise<LocalKnowledgeAsyncParseJob[]>;
+    updateAsyncParseJobCacheStatus(params: {
+        jobId: string;
+        cacheStatus: KnowledgeAsyncCacheStatus;
+        localDocumentId?: string;
+    }): Promise<void>;
+    listDocuments(): Promise<LocalKnowledgeDocument[]>;
+    getDocument(localDocumentId: string): Promise<LocalKnowledgeDocument | undefined>;
+    loadResult(localDocumentId: string): Promise<{
+        document: LocalKnowledgeDocument;
+        result: ParseResult;
+    }>;
+    private getResultDirectoryPath;
+    private loadStoredResult;
+    private readIndex;
+    private writeIndex;
+}
+
 /**
  * Main Knowhere SDK client
  */
@@ -897,6 +1163,8 @@ declare class Knowhere {
     readonly retrieval: Retrieval;
     /** Documents resource for canonical document lifecycle operations */
     readonly documents: Documents;
+    /** Client-side local knowledge tools over parsed Knowhere results */
+    readonly knowledge: Knowledge;
     private httpClient;
     /**
      * Create a new Knowhere client
@@ -923,6 +1191,12 @@ declare class Knowhere {
      * ```
      */
     parse(params: ParseParams): Promise<ParseResult>;
+    /**
+     * 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.
+     */
+    startParse(params: ParseParams): Promise<Job>;
 }
 
 declare const VERSION = "0.1.0";
@@ -1056,4 +1330,4 @@ declare class JobFailedError extends KnowhereError {
     constructor(message: string, code: string, jobResult: JobResult);
 }
 
-export { APIError, AuthenticationError, BadRequestError, type BaseChunk, ChecksumError, type Chunk, ConflictError, type CreateJobParams, type DocType, type Document, type DocumentChunk, type DocumentChunkGetParams, type DocumentChunkListParams, type DocumentChunkListResponse, type DocumentChunkPagination, type DocumentChunkResponse, type DocumentChunkType, type DocumentListResponse, Documents, type FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, KnowhereError, type KnowhereOptions, type LoadOptions, type Manifest, NetworkError, NotFoundError, type ParseParams, type ParseResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, Retrieval, type RetrievalChannel, type RetrievalFilterMode, type RetrievalQueryParams, type RetrievalQueryResponse, type RetrievalResult, type RetrievalSectionExclusion, type RetrievalSource, ServiceUnavailableError, type Statistics, type TableChunk, type TextChunk, TimeoutError, type UploadParams, type UploadProgress, VERSION, ValidationError, type WaitOptions, type WebhookConfig, Knowhere as default };
+export { APIError, type AuthTokenProvider, AuthenticationError, BadRequestError, type BaseChunk, ChecksumError, type Chunk, ConflictError, type CreateJobParams, type DocType, type Document, type DocumentChunk, type DocumentChunkGetParams, type DocumentChunkListParams, type DocumentChunkListResponse, type DocumentChunkPagination, type DocumentChunkResponse, type DocumentChunkType, type DocumentListResponse, Documents, type FileIndex, GatewayTimeoutError, type ImageChunk, InternalServerError, InvalidStateError, type Job, type JobError, JobFailedError, type JobResult, type JobStatus, Jobs, Knowhere, KnowhereError, type KnowhereOptions, Knowledge, type KnowledgeAsyncJobStatusResponse, type KnowledgeAsyncParseParams, type KnowledgeAsyncParseResponse, type KnowledgeCacheJobResultParams, type KnowledgeChunkType, type KnowledgeGrepMatch, type KnowledgeGrepParams, type KnowledgeGrepResponse, type KnowledgeOutline, type KnowledgeParseParams, type KnowledgeReadChunk, type KnowledgeReadParams, type KnowledgeReadResponse, type KnowledgeSearchParams, type KnowledgeSearchReference, type KnowledgeSearchResponse, type KnowledgeSearchResult, type KnowledgeSection, type KnowledgeStartupRecoveryResponse, type LoadOptions, type LocalKnowledgeDocument, type LocalKnowledgeParseResponse, LocalKnowledgeStore, type Manifest, NetworkError, NotFoundError, type ParseParams, type ParseResult, type ParsingModel, type ParsingParams, PaymentRequiredError, PermissionDeniedError, type PollProgress, PollingTimeoutError, RateLimitError, Retrieval, type RetrievalChannel, type RetrievalFilterMode, type RetrievalQueryParams, type RetrievalQueryResponse, type 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 };