@botpress/adk 1.7.19 → 1.8.1

package/dist/knowledge/index.d.ts

@@ -0,0 +1,6 @@
+export { KnowledgeManager } from './manager.js';
+export type { KnowledgeManagerOptions } from './manager.js';
+export { KBSyncOperation } from './types.js';
+export type { SyncOutputItem, SyncErrorItem, SyncOutput, LocalKnowledgeBase, KBSyncItem, KBSyncPlan, KBSyncOptions, KBSyncResult, WebsiteSyncInfo, OrphanedSource, OrphanedSourceStatus, SourceSyncStatus, FileChanges, } from './types.js';
+export { KBSyncFormatter } from './sync-formatter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/knowledge/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/knowledge/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAC/C,YAAY,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAC5C,YAAY,EACV,cAAc,EACd,aAAa,EACb,UAAU,EACV,kBAAkB,EAClB,UAAU,EACV,UAAU,EACV,aAAa,EACb,YAAY,EACZ,eAAe,EACf,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,WAAW,GACZ,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/knowledge/manager.d.ts

@@ -0,0 +1,141 @@
+import { Client } from '@botpress/client';
+import { AgentProject } from '../agent-project/agent-project.js';
+import { LocalKnowledgeBase, KBSyncPlan, KBSyncResult, KBSyncOptions, OrphanedSource } from './types.js';
+type RemoteKnowledgeBase = Pick<Awaited<ReturnType<Client['listKnowledgeBases']>>['knowledgeBases'][number], 'id' | 'name' | 'tags'>;
+export interface KnowledgeManagerOptions {
+    project: AgentProject;
+    botId?: string;
+}
+/**
+ * Manages knowledge base synchronization for ADK projects
+ */
+export declare class KnowledgeManager {
+    private client?;
+    private botId?;
+    private project;
+    /** Cache of file hashes by directory path to avoid recalculating */
+    private fileHashCache;
+    constructor(options: KnowledgeManagerOptions);
+    /**
+     * Clear the file hash cache (call before a new sync operation)
+     */
+    clearHashCache(): void;
+    private getClient;
+    private assertBotId;
+    /**
+     * Format an error for display, including API response data if available
+     */
+    private formatError;
+    /**
+     * Get all knowledge bases from the project
+     */
+    getLocalKnowledgeBases(): LocalKnowledgeBase[];
+    /**
+     * Calculate content hash from individual file hashes
+     * This creates a deterministic hash of all file contents
+     */
+    private computeContentHash;
+    /**
+     * List all remote knowledge bases
+     */
+    private listRemoteKnowledgeBases;
+    /**
+     * Find remote KB by name
+     */
+    private findRemoteKB;
+    /**
+     * Create a new knowledge base
+     */
+    createKnowledgeBase(name: string): Promise<RemoteKnowledgeBase>;
+    /**
+     * Get remote KBs that don't exist locally (orphaned)
+     */
+    getOrphanedKBs(): Promise<RemoteKnowledgeBase[]>;
+    /**
+     * Get orphaned sources for a KB by listing files and extracting unique sourceIds from tags
+     * Returns sources that exist in remote files but not in local definition
+     */
+    getOrphanedSources(kbName: string, localSourceIds: string[]): Promise<OrphanedSource[]>;
+    /**
+     * Delete all files belonging to an orphaned source using direct sourceId tag query
+     */
+    deleteOrphanedSource(kbName: string, sourceId: string): Promise<{
+        deletedFiles: number;
+        errors: string[];
+    }>;
+    /**
+     * Clean up source tags from KB after deleting orphaned source
+     * Note: Botpress API merges tags, so we set to empty string to "delete" them
+     */
+    private cleanupSourceTags;
+    /**
+     * Delete a KB and all its associated files
+     */
+    deleteKnowledgeBase(kbId: string, kbName: string): Promise<{
+        deletedFiles: number;
+    }>;
+    /**
+     * Get stored hash for a specific source from KB tags
+     */
+    private getRemoteSourceHash;
+    /**
+     * Update source hash in KB tags after sync
+     */
+    private updateSourceHash;
+    /**
+     * Compute config hash for a data source (used for website sources)
+     */
+    private computeConfigHash;
+    /**
+     * Trigger website source sync by creating the builtin_knowledge_indexing workflow.
+     * This requires adk dev to be running as the workflow executes in the bot runtime.
+     */
+    syncWebsiteSource(kbName: string, force: boolean): Promise<{
+        workflowId: string;
+    }>;
+    /**
+     * Check if a KB has any website sources
+     */
+    hasWebsiteSources(kbName: string): boolean;
+    /**
+     * Get list of KB names that have website sources
+     */
+    getKBsWithWebsiteSources(): string[];
+    /**
+     * Compute content hash for a single directory source
+     */
+    private computeDirectorySourceHash;
+    /**
+     * Create a sync plan comparing local sources vs remote KB tags
+     * Uses per-source hashes stored in KB tags
+     */
+    createSyncPlan(): Promise<KBSyncPlan>;
+    /**
+     * Detect file changes for a single directory source
+     */
+    private detectDirectorySourceChanges;
+    /**
+     * Scan local files for a directory source and return their hashes
+     */
+    private scanLocalFileHashes;
+    /**
+     * Execute KB sync based on plan
+     * Directly uploads files to Botpress without requiring a running bot.
+     * For website sources that need sync, triggers the builtin_knowledge_indexing workflow.
+     */
+    executeSync(plan: KBSyncPlan, options?: KBSyncOptions): Promise<KBSyncResult>;
+    /**
+     * Sync a directory data source by uploading files directly
+     */
+    private syncDirectorySource;
+    /**
+     * List existing files in Botpress with given tags
+     */
+    private listExistingFiles;
+    /**
+     * Upload or update a file
+     */
+    private upsertFile;
+}
+export {};
+//# sourceMappingURL=manager.d.ts.map

package/dist/knowledge/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/knowledge/manager.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAIzC,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAA;AAChE,OAAO,EACL,kBAAkB,EAClB,UAAU,EACV,YAAY,EAGZ,aAAa,EAKb,cAAc,EAEf,MAAM,YAAY,CAAA;AAEnB,KAAK,mBAAmB,GAAG,IAAI,CAC7B,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,MAAM,CAAC,EAC3E,IAAI,GAAG,MAAM,GAAG,MAAM,CACvB,CAAA;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,YAAY,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAkDD;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,CAAQ;IACvB,OAAO,CAAC,KAAK,CAAC,CAAQ;IACtB,OAAO,CAAC,OAAO,CAAc;IAC7B,oEAAoE;IACpE,OAAO,CAAC,aAAa,CAAiD;gBAE1D,OAAO,EAAE,uBAAuB;IAK5C;;OAEG;IACH,cAAc,IAAI,IAAI;YAIR,SAAS;IAkBvB,OAAO,CAAC,WAAW;IASnB;;OAEG;IACH,OAAO,CAAC,WAAW;IAoBnB;;OAEG;IACH,sBAAsB,IAAI,kBAAkB,EAAE;IAgB9C;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAO1B;;OAEG;YACW,wBAAwB;IActC;;OAEG;YACW,YAAY;IAK1B;;OAEG;IACG,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAWrE;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAMtD;;;OAGG;IACG,kBAAkB,CACtB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EAAE,GACvB,OAAO,CAAC,cAAc,EAAE,CAAC;IAuC5B;;OAEG;IACG,oBAAoB,CACxB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IA0BtD;;;OAGG;YACW,iBAAiB;IAoB/B;;OAEG;IACG,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IAyB1F;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;OAEG;YACW,gBAAgB;IAc9B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;;OAGG;IACG,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAaxF;;OAEG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAM1C;;OAEG;IACH,wBAAwB,IAAI,MAAM,EAAE;IAMpC;;OAEG;YACW,0BAA0B;IAQxC;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,UAAU,CAAC;IAuJ3C;;OAEG;YACW,4BAA4B;IAgD1C;;OAEG;YACW,mBAAmB;IA4BjC;;;;OAIG;IACG,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;IA+IvF;;OAEG;YACW,mBAAmB;IA6GjC;;OAEG;YACW,iBAAiB;IAqB/B;;OAEG;YACW,UAAU;CAqDzB"}

package/dist/knowledge/sync-formatter.d.ts

@@ -0,0 +1,9 @@
+import type { KBSyncPlan } from './types.js';
+/**
+ * Plain text formatter for KB sync plan
+ * CLI-agnostic - the CLI should apply colors/styling
+ */
+export declare class KBSyncFormatter {
+    static format(plan: KBSyncPlan, kbsWithWebsites?: string[]): string;
+}
+//# sourceMappingURL=sync-formatter.d.ts.map

package/dist/knowledge/sync-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-formatter.d.ts","sourceRoot":"","sources":["../../src/knowledge/sync-formatter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAsB5C;;;GAGG;AACH,qBAAa,eAAe;IAC1B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,eAAe,GAAE,MAAM,EAAO,GAAG,MAAM;CA0FxE"}

package/dist/knowledge/types.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Sync output from KB indexing workflow
+ * Mirrors the SyncOutput from runtime
+ */
+export interface SyncOutputItem {
+    file: string;
+    name: string;
+    hash: string;
+    size: number;
+}
+export interface SyncErrorItem {
+    file: string;
+    error: string;
+}
+export interface SyncOutput {
+    processed: number;
+    added: SyncOutputItem[];
+    updated: SyncOutputItem[];
+    deleted: SyncOutputItem[];
+    errors: SyncErrorItem[];
+}
+/**
+ * Local knowledge base representation from project
+ */
+export interface LocalKnowledgeBase {
+    name: string;
+    description?: string;
+    sourceCount: number;
+}
+/**
+ * Sync operation type for knowledge bases
+ */
+export declare enum KBSyncOperation {
+    Sync = "sync",
+    Skip = "skip"
+}
+/**
+ * File changes detected during sync planning
+ */
+export interface FileChanges {
+    added: string[];
+    modified: string[];
+    deleted: string[];
+}
+/**
+ * Sync status for a single data source
+ */
+export interface SourceSyncStatus {
+    sourceId: string;
+    sourceType: 'directory' | 'website';
+    needsSync: boolean;
+    reason: string;
+    /** For directory sources, detailed file changes */
+    fileChanges?: FileChanges;
+}
+/**
+ * Represents an orphaned source (exists remotely but not in local definition)
+ */
+export interface OrphanedSource {
+    sourceId: string;
+    fileCount: number;
+}
+/**
+ * Status for orphaned sources in the sync plan
+ */
+export interface OrphanedSourceStatus {
+    sourceId: string;
+    fileCount: number;
+    willDelete: boolean;
+}
+/**
+ * Individual KB sync plan item
+ */
+export interface KBSyncItem {
+    operation: KBSyncOperation;
+    kb: LocalKnowledgeBase;
+    reason: string;
+    /** Whether the KB needs to be created remotely first */
+    needsCreation?: boolean;
+    /** Per-source sync status */
+    sources?: SourceSyncStatus[];
+    /** Orphaned sources that exist remotely but not in local definition */
+    orphanedSources?: OrphanedSourceStatus[];
+}
+/**
+ * Sync plan for all knowledge bases
+ */
+export interface KBSyncPlan {
+    items: KBSyncItem[];
+    toSync: number;
+    toSkip: number;
+    hasChanges: boolean;
+    /** Source-level counts */
+    sourcesToSync: number;
+    sourcesToSkip: number;
+    /** Number of orphaned sources to delete */
+    orphanedSourcesToDelete: number;
+}
+/**
+ * Options for KB sync execution
+ */
+export interface KBSyncOptions {
+    /** Force sync even if config hash matches */
+    force?: boolean;
+    /** Timeout in ms for waiting for workflow completion (default: 300000 = 5 min) */
+    timeout?: number;
+    /** Auto-confirm operations without prompting */
+    autoConfirm?: boolean;
+}
+/**
+ * Website sync workflow info
+ */
+export interface WebsiteSyncInfo {
+    kbName: string;
+    workflowId: string;
+}
+/**
+ * Result of KB sync execution
+ */
+export interface KBSyncResult {
+    synced: Array<{
+        name: string;
+        result: SyncOutput;
+    }>;
+    skipped: Array<{
+        name: string;
+        reason: string;
+    }>;
+    failed: Array<{
+        name: string;
+        error: string;
+    }>;
+    /** Website sync workflows triggered (run asynchronously in bot runtime) */
+    websiteSyncs?: WebsiteSyncInfo[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/knowledge/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/knowledge/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,cAAc,EAAE,CAAA;IACvB,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,MAAM,EAAE,aAAa,EAAE,CAAA;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;GAEG;AACH,oBAAY,eAAe;IACzB,IAAI,SAAS;IACb,IAAI,SAAS;CACd;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,WAAW,GAAG,SAAS,CAAA;IACnC,SAAS,EAAE,OAAO,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,mDAAmD;IACnD,WAAW,CAAC,EAAE,WAAW,CAAA;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,OAAO,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,eAAe,CAAA;IAC1B,EAAE,EAAE,kBAAkB,CAAA;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,wDAAwD;IACxD,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,6BAA6B;IAC7B,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAA;IAC5B,uEAAuE;IACvE,eAAe,CAAC,EAAE,oBAAoB,EAAE,CAAA;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,UAAU,EAAE,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,OAAO,CAAA;IACnB,0BAA0B;IAC1B,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,2CAA2C;IAC3C,uBAAuB,EAAE,MAAM,CAAA;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,6CAA6C;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,gDAAgD;IAChD,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,UAAU,CAAA;KAAE,CAAC,CAAA;IACnD,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAChD,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC9C,2EAA2E;IAC3E,YAAY,CAAC,EAAE,eAAe,EAAE,CAAA;CACjC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botpress/adk",
-  "version": "1.7.19",
+  "version": "1.8.1",
   "description": "Core ADK library for building AI agents on Botpress",
   "type": "module",
   "main": "dist/index.js",
@@ -47,7 +47,7 @@
     "@botpress/cli": "^4.23",
     "@botpress/client": "^1.27.2",
     "@botpress/cognitive": "^0.2.0",
-    "@botpress/runtime": "^1.7.19",
+    "@botpress/runtime": "^1.8.1",
     "@botpress/sdk": "^4.18.1",
     "@bpinternal/yargs-extra": "^0.0.21",
     "@parcel/watcher": "^2.5.1",