@ontos-ai/knowhere-claw 0.2.0 → 0.2.2

package/dist/store.d.ts

@@ -0,0 +1,79 @@
+import type { ChannelRouteRecord, KnowhereScope, PluginLogger, SaveStoredDocumentPayload, ScopeMode, StoredDocumentPayload, StoredDocumentRecord } from "./types";
+export declare class KnowhereStore {
+    private readonly rootDir;
+    private readonly scopeMode;
+    private readonly logger;
+    private readonly indexCache;
+    private readonly documentPayloadCache;
+    private readonly scopeAccessChains;
+    private readonly scopeKeyAliases;
+    private readonly sessionScopeKeysBySessionId;
+    private readonly sessionScopeKeysBySessionKey;
+    private readonly channelRoutes;
+    private routesLoaded;
+    constructor(params: {
+        rootDir: string;
+        scopeMode: ScopeMode;
+        logger: PluginLogger;
+    });
+    registerScopeAlias(context: {
+        scopeKey: string;
+        sessionKey?: string;
+        sessionId?: string;
+    }): string;
+    registerMessageScope(context: {
+        sessionKey?: string;
+        sessionId?: string;
+        messageContext: unknown;
+    }): string | undefined;
+    registerChannelRoute(params: {
+        channelId: string;
+        accountId?: string;
+        conversationId?: string;
+    }): Promise<void>;
+    resolveChannelRoute(params: {
+        channelId?: string;
+        conversationId?: string;
+        sessionKey?: string;
+    }): Promise<ChannelRouteRecord | undefined>;
+    private lookupChannelRoute;
+    inheritScopeAlias(context: {
+        childSessionKey?: string;
+        childSessionId?: string;
+        requesterSessionKey?: string;
+        requesterSessionId?: string;
+    }): string | undefined;
+    resolveScope(context?: {
+        agentId?: string;
+        sessionKey?: string;
+        sessionId?: string;
+    }): KnowhereScope;
+    listDocuments(scope: KnowhereScope): Promise<StoredDocumentRecord[]>;
+    loadDocumentPayload(scope: KnowhereScope, docId: string): Promise<StoredDocumentPayload | null>;
+    getResultFileAbsolutePath(scope: KnowhereScope, docId: string, relativePath: string): string;
+    readResultFile(scope: KnowhereScope, docId: string, relativePath: string): Promise<{
+        document: StoredDocumentRecord;
+        relativePath: string;
+        text: string | null;
+    } | null>;
+    saveDownloadedDocument(scope: KnowhereScope, payload: SaveStoredDocumentPayload, options?: {
+        overwrite?: boolean;
+    }): Promise<StoredDocumentRecord>;
+    removeDocument(scope: KnowhereScope, docId: string): Promise<StoredDocumentRecord | null>;
+    clearScope(scope: KnowhereScope): Promise<StoredDocumentRecord[]>;
+    private getIndex;
+    private persistIndex;
+    private runWithScopeAccessLock;
+    private removeDocumentArtifacts;
+    private buildDocumentPayloadCacheKey;
+    private touchDocumentPayloadCache;
+    private deleteDocumentPayloadCache;
+    private deleteScopeDocumentPayloadCaches;
+    private loadOrBuildBrowseIndex;
+    private buildRouteKey;
+    private ensureRoutesLoaded;
+    private persistRoutes;
+    private resolveCanonicalScopeKey;
+    private resolveKnownScopeKey;
+    private rebuildIndex;
+}

package/dist/text.d.ts

@@ -0,0 +1,10 @@
+export declare function normalizeWhitespace(value: unknown): string;
+export declare function truncateText(value: unknown, maxChars: number): string;
+export declare function slugify(value: unknown, fallback?: string): string;
+export declare function hashString(value: string): string;
+export declare function sanitizeStringArray(value: unknown): string[];
+export declare function toComparableText(value: unknown): string;
+export declare function stripHtmlTags(text: string): string;
+export declare function stripLatex(text: string): string;
+export declare function normalizeUnicode(text: string): string;
+export declare function normalizeForGrep(text: string): string;

package/dist/tools.d.ts

@@ -0,0 +1,10 @@
+import { type AnyAgentTool, type OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { KnowhereStore } from "./store";
+import type { KnowledgeGraphService } from "./kg-service";
+import type { ResolvedKnowhereConfig, ToolRuntimeContext } from "./types";
+export declare function createKnowhereToolFactory(params: {
+    api: OpenClawPluginApi;
+    config: ResolvedKnowhereConfig;
+    store: KnowhereStore;
+    kgService: KnowledgeGraphService;
+}): (ctx: ToolRuntimeContext) => AnyAgentTool[];

package/dist/tracker-progress.d.ts

@@ -0,0 +1,10 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import type { ChannelRouteRecord } from "./types";
+export declare function sendTrackerProgress(params: {
+    api: OpenClawPluginApi;
+    context?: unknown;
+    sessionKey?: string;
+    messages?: unknown[];
+    channelRoute?: ChannelRouteRecord;
+    text: string;
+}): Promise<boolean>;

package/dist/types.d.ts

@@ -0,0 +1,320 @@
+export type ScopeMode = "session" | "agent" | "global";
+export type StringRecord = Record<string, unknown>;
+export interface PluginLogger {
+    debug?: (message: string) => void;
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+}
+export interface ToolRuntimeContext {
+    workspaceDir?: string;
+    agentId?: string;
+    accountId?: string;
+    sessionKey?: string;
+    sessionId?: string;
+}
+export interface ResolvedKnowhereConfig {
+    apiKey: string;
+    baseUrl: string;
+    storageDir: string;
+    scopeMode: ScopeMode;
+    pollIntervalMs: number;
+    pollTimeoutMs: number;
+    requestTimeoutMs: number;
+    uploadTimeoutMs: number;
+}
+export interface KnowhereStatistics {
+    total_chunks?: number;
+    text_chunks?: number;
+    image_chunks?: number;
+    table_chunks?: number;
+    total_pages?: number;
+}
+export interface KnowhereChecksum {
+    algorithm?: string;
+    value?: string;
+}
+export interface KnowhereManifest {
+    version?: string;
+    job_id?: string;
+    data_id?: string;
+    source_file_name?: string;
+    processing_date?: string;
+    checksum?: KnowhereChecksum;
+    statistics?: KnowhereStatistics;
+    files?: StringRecord;
+}
+export interface StoredChunk {
+    chunkId: string;
+    type: "text" | "image" | "table";
+    path: string | null;
+    summary: string;
+    content: string;
+    tokens: number | null;
+    keywords: string[];
+    relationships: unknown[];
+    metadata: StringRecord;
+    assetFilePath: string | null;
+    originalName: string | null;
+    tableType: string | null;
+}
+export interface StoredPathRecord {
+    path: string;
+    parentPath: string | null;
+    depth: number;
+    childPaths: string[];
+    chunkIds: string[];
+    directChunkCount: number;
+    chunkCount: number;
+    textChunkCount: number;
+    imageChunkCount: number;
+    tableChunkCount: number;
+}
+export type StoredResultFileKind = "manifest" | "chunks" | "fullMarkdown" | "kbCsv" | "hierarchy" | "hierarchyView" | "image" | "table" | "other";
+export interface StoredResultFileRecord {
+    relativePath: string;
+    kind: StoredResultFileKind;
+    chunkId: string | null;
+    format: string | null;
+    sizeBytes: number | null;
+}
+export interface StoredBrowseIndex {
+    version: number;
+    paths: StoredPathRecord[];
+    chunkOrder: string[];
+    resultFiles: StoredResultFileRecord[];
+}
+export interface KnowhereParseResult {
+    manifest: KnowhereManifest;
+    chunks: StoredChunk[];
+    fullMarkdown: string;
+    hierarchy: unknown;
+    browseIndex: StoredBrowseIndex;
+}
+export interface KnowhereDownloadedResult {
+    zipBytes: Buffer;
+    rawZipSha1: string;
+}
+export interface KnowhereJob {
+    job_id: string;
+    status: string;
+    source_type: string;
+    data_id?: string | null;
+    created_at?: string | null;
+    upload_url?: string | null;
+    upload_headers?: Record<string, string> | null;
+    expires_in?: number | null;
+}
+export interface KnowhereJobError {
+    code?: string;
+    message?: string;
+    request_id?: string;
+    details?: unknown;
+}
+export interface KnowhereJobResult {
+    job_id: string;
+    status: string;
+    source_type: string;
+    data_id?: string | null;
+    created_at?: string | null;
+    progress?: unknown;
+    error?: KnowhereJobError | null;
+    result?: StringRecord | null;
+    result_url?: string | null;
+    result_url_expires_at?: string | null;
+    file_name?: string | null;
+    file_extension?: string | null;
+    model?: string | null;
+    ocr_enabled?: boolean | null;
+    duration_seconds?: number | null;
+    credits_spent?: number | null;
+}
+export interface KnowhereJobList {
+    jobs: KnowhereJobResult[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+}
+export interface KnowhereJobListRequest {
+    page?: number;
+    pageSize?: number;
+    jobStatus?: string;
+    jobType?: string;
+    recentDays?: 1 | 7 | 30;
+    startTime?: string;
+    endTime?: string;
+}
+export interface KnowhereParsingParams {
+    model?: "base" | "advanced";
+    ocr_enabled?: boolean;
+    kb_dir?: string;
+    doc_type?: string;
+    smart_title_parse?: boolean;
+    summary_image?: boolean;
+    summary_table?: boolean;
+    summary_txt?: boolean;
+    add_frag_desc?: string;
+}
+export interface KnowhereIngestRequest {
+    filePath?: string;
+    fileName?: string;
+    url?: string;
+    dataId?: string;
+    parsingParams?: KnowhereParsingParams;
+    onJobCreated?: (job: KnowhereJob) => void | Promise<void>;
+    onJobUpdated?: (jobResult: KnowhereJobResult) => void | Promise<void>;
+}
+export interface KnowhereIngestResult {
+    job: KnowhereJob;
+    jobResult: KnowhereJobResult;
+    downloadedResult: KnowhereDownloadedResult;
+}
+export interface KnowhereScope {
+    mode: ScopeMode | "global";
+    key: string;
+    label: string;
+    rootDir: string;
+    documentsDir: string;
+    indexPath: string;
+}
+export interface StoredDocumentRecord {
+    id: string;
+    title: string;
+    sourceType: "file" | "url";
+    source: string;
+    sourceLabel: string;
+    fileName: string | null;
+    originalFileName: string | null;
+    dataId: string | null;
+    jobId: string | null;
+    checksum: string | null;
+    resultUrl: string | null;
+    resultUrlExpiresAt: string | null;
+    scopeLabel: string;
+    tags: string[];
+    ingestedAt: string;
+    updatedAt: string;
+    chunkCount: number;
+    statistics: KnowhereStatistics;
+}
+export interface StoredDocumentPayload {
+    version: number;
+    document: StoredDocumentRecord;
+    manifest: KnowhereManifest;
+    jobResult: KnowhereJobResult;
+    fullMarkdown: string;
+    hierarchy: unknown;
+    browseIndex: StoredBrowseIndex;
+    rawZipSha1: string;
+    chunks: StoredChunk[];
+}
+export interface StoredDocumentMetadata {
+    version: number;
+    document: StoredDocumentRecord;
+    jobResult: KnowhereJobResult;
+    rawZipSha1: string;
+}
+export interface KnowhereIndex {
+    version: number;
+    scopeMode: string;
+    scopeKey: string;
+    updatedAt: string | null;
+    documents: StoredDocumentRecord[];
+}
+export interface SaveStoredDocumentPayload {
+    sourceType: "file" | "url";
+    source: string;
+    sourceLabel?: string;
+    fileName: string | null;
+    docId?: string;
+    title?: string;
+    dataId?: string;
+    tags: string[];
+    job: KnowhereJob;
+    jobResult: KnowhereJobResult;
+    downloadedResult: KnowhereDownloadedResult;
+}
+export interface JsonSchemaObject {
+    [key: string]: unknown;
+}
+export interface ChannelRouteRecord {
+    readonly channelId: string;
+    readonly accountId: string;
+    readonly conversationId?: string;
+    readonly updatedAt: string;
+}
+export declare function isRecord(value: unknown): value is StringRecord;
+export declare function isNodeError(error: unknown): error is NodeJS.ErrnoException;
+export type KbIdSource = "disabled" | "agent" | "agent-session" | "global";
+export interface KnowledgeGraphConnectConfig {
+    minKeywordOverlap: number;
+    keywordScoreWeight: number;
+    maxConnectionsPerChunk: number;
+    minScoreThreshold: number;
+    crossFileOnly: boolean;
+    maxContentOverlap: number;
+}
+export interface KnowledgeGraphConfig {
+    enableKnowledgeGraph: boolean;
+    kbId?: string;
+    kbIdSource?: KbIdSource;
+    concurrentBuildStrategy?: "queue" | "skip";
+    buildTimeout?: number;
+    notifyOnGraphFailure?: boolean;
+    connectConfig?: Partial<KnowledgeGraphConnectConfig>;
+}
+export interface GraphConnection {
+    source: string;
+    target: string;
+    score: number;
+    sharedKeywords: string[];
+    connectionType: string;
+}
+/**
+ * File-level edge in knowledge graph (matches SKILL.md schema)
+ */
+export interface FileEdge {
+    source: string;
+    target: string;
+    connection_count: number;
+    avg_score: number;
+    top_connections: Array<{
+        source_chunk: string;
+        source_id: string;
+        target_chunk: string;
+        target_id: string;
+        relation: string;
+        score: number;
+    }>;
+}
+/**
+ * File metadata in knowledge graph (matches SKILL.md schema)
+ */
+export interface FileMetadata {
+    chunks_count: number;
+    types: Record<string, number>;
+    top_keywords: string[];
+    top_summary: string;
+    importance: number;
+}
+/**
+ * Knowledge graph structure (matches SKILL.md schema)
+ */
+export interface KnowledgeGraph {
+    version: string;
+    stats: {
+        total_files: number;
+        total_chunks: number;
+        total_cross_file_edges: number;
+    };
+    files: Record<string, FileMetadata>;
+    edges: FileEdge[];
+}
+export interface KbMetadata {
+    kbId: string;
+    createdAt: string;
+    lastUpdated: string;
+    documentCount: number;
+    config: Partial<KnowledgeGraphConnectConfig>;
+}

package/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "name": "Knowhere",
   "description": "Parse documents with Knowhere and expose the stored result as tool-queryable document state for OpenClaw agents.",
   "skills": ["./skills"],
-  "version": "0.1.5",
+  "version": "0.2.2",
   "uiHints": {
     "apiKey": {
       "label": "Knowhere API Key",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontos-ai/knowhere-claw",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "OpenClaw plugin for Knowhere-powered document ingestion and automatic grounding.",
   "files": [
     "dist/",
@@ -18,13 +18,14 @@
     }
   },
   "scripts": {
-    "build": "rolldown -c",
+    "build": "rolldown -c && tsc -p tsconfig.build.json",
     "changeset": "changeset",
     "changeset:publish": "changeset publish",
     "fmt": "oxfmt",
     "fmt:check": "oxfmt --check",
     "lint": "oxlint --type-aware",
     "lint:fix": "oxlint --type-aware --fix",
+    "smoke:auto": "vite-node --mode smoke ./smoketest/run-tool.ts -- --auto --file-path smoketest/fixtures/sample.pdf",
     "smoke:tools": "vite-node --mode smoke ./smoketest/run-tool.ts",
     "release:beta": "node ./scripts/publish-beta-release.mjs",
     "release:publish": "node ./scripts/publish-release.mjs",
@@ -69,4 +70,4 @@
       "./dist/index.js"
     ]
   }
-}
+}