@toolpack-sdk/knowledge 3.0.0 → 3.2.0

package/dist/index.d.cts

@@ -101,6 +101,8 @@ interface KnowledgeOptions {
     onError?: ErrorHandler;
     onSync?: SyncEventHandler;
     onEmbeddingProgress?: EmbeddingProgressHandler;
+    onAdd?: KnowledgeAddHandler;
+    onDelete?: KnowledgeDeleteHandler;
     streamingBatchSize?: number;
 }
 type ErrorHandler = (error: Error, context: {
@@ -121,6 +123,17 @@ interface EmbeddingProgressEvent {
     percent: number;
 }
 type EmbeddingProgressHandler = (event: EmbeddingProgressEvent) => void;
+interface KnowledgeAddEvent {
+    id: string;
+    content: string;
+    metadata: Record<string, unknown>;
+}
+type KnowledgeAddHandler = (event: KnowledgeAddEvent) => void;
+interface KnowledgeDeleteEvent {
+    ids: string[];
+    filter?: MetadataFilter;
+}
+type KnowledgeDeleteHandler = (event: KnowledgeDeleteEvent) => void;
 declare class Knowledge {
     private provider;
     private embedder;
@@ -144,6 +157,21 @@ declare class Knowledge {
      * @returns The ID of the added chunk
      */
     add(content: string, metadata?: Record<string, unknown>): Promise<string>;
+    /**
+     * Embeds and stores all chunks from a source without clearing existing data.
+     * Use this for adding or updating individual items in a persistent store.
+     * Returns the number of chunks ingested.
+     */
+    ingest(source: KnowledgeSource): Promise<number>;
+    delete(ids: string[]): Promise<void>;
+    /**
+     * Deletes all chunks whose metadata matches every key-value pair in the
+     * filter. Returns the IDs of the deleted chunks.
+     *
+     * Useful for cascade-deleting all chunks that belong to a platform item:
+     *   `knowledge.deleteWhere({ knowledge_item_id: "abc" })`
+     */
+    deleteWhere(filter: MetadataFilter): Promise<string[]>;
     stop(): Promise<void>;
     toTool(): KnowledgeTool;
 }
@@ -257,6 +285,22 @@ declare class MarkdownSource implements KnowledgeSource {
     private generateChunkId;
 }
 
+interface TextSourceOptions {
+    maxChunkSize?: number;
+    chunkOverlap?: number;
+    namespace?: string;
+    metadata?: Record<string, unknown>;
+}
+declare class TextSource implements KnowledgeSource {
+    private name;
+    private content;
+    private options;
+    constructor(name: string, content: string, options?: TextSourceOptions);
+    load(): AsyncIterable<Chunk>;
+    private chunkText;
+    private chunkId;
+}
+
 interface WebUrlSourceOptions {
     maxChunkSize?: number;
     chunkOverlap?: number;
@@ -470,6 +514,12 @@ interface VertexAIEmbedderOptions {
      * Example: 500 adds a 0.5s pause between batches (120 QPM effective rate).
      */
     rateLimitMs?: number;
+    /**
+     * Inline service account credentials object (parsed JSON key).
+     * When provided, used instead of Application Default Credentials.
+     * Mirrors the googleAuthOptions.credentials pattern in VertexAIAdapter.
+     */
+    credentials?: Record<string, unknown>;
 }
 declare class VertexAIEmbedder implements Embedder {
     readonly dimensions: number;
@@ -480,6 +530,7 @@ declare class VertexAIEmbedder implements Embedder {
     private readonly retries;
     private readonly retryDelay;
     private readonly rateLimitMs;
+    private readonly credentials?;
     private lastEmbedAt;
     constructor(options?: VertexAIEmbedderOptions);
     embed(text: string): Promise<number[]>;
@@ -491,4 +542,6 @@ declare class VertexAIEmbedder implements Embedder {
 declare function keywordSearch(text: string, query: string): number;
 declare function combineScores(semanticScore: number, keywordScore: number, semanticWeight?: number): number;
 
-export { ApiDataSource, type ApiDataSourceOptions, type Chunk, ChunkTooLargeError, type ChunkUpdate, DimensionMismatchError, type Embedder, EmbeddingError, type EmbeddingProgressEvent, type EmbeddingProgressHandler, type ErrorHandler, IngestionError, JSONSource, type JSONSourceOptions, Knowledge, KnowledgeError, type KnowledgeOptions, type KnowledgeProvider, KnowledgeProviderError, type KnowledgeSource, type KnowledgeTool, type KnowledgeToolParams, type KnowledgeToolResult, MarkdownSource, type MarkdownSourceOptions, MemoryProvider, type MemoryProviderOptions, type MetadataFilter, OllamaEmbedder, type OllamaEmbedderOptions, OpenAIEmbedder, type OpenAIEmbedderOptions, OpenRouterEmbedder, type OpenRouterEmbedderOptions, PersistentKnowledgeProvider, type PersistentKnowledgeProviderOptions, PostgresSource, type PostgresSourceOptions, type QueryOptions, type QueryResult, SQLiteSource, type SQLiteSourceOptions, type SyncEvent, type SyncEventHandler, VertexAIEmbedder, type VertexAIEmbedderOptions, WebUrlSource, type WebUrlSourceOptions, combineScores, keywordSearch };
+declare function matchesFilter(metadata: Record<string, unknown>, filter?: MetadataFilter): boolean;
+
+export { ApiDataSource, type ApiDataSourceOptions, type Chunk, ChunkTooLargeError, type ChunkUpdate, DimensionMismatchError, type Embedder, EmbeddingError, type EmbeddingProgressEvent, type EmbeddingProgressHandler, type ErrorHandler, IngestionError, JSONSource, type JSONSourceOptions, Knowledge, type KnowledgeAddEvent, type KnowledgeAddHandler, type KnowledgeDeleteEvent, type KnowledgeDeleteHandler, KnowledgeError, type KnowledgeOptions, type KnowledgeProvider, KnowledgeProviderError, type KnowledgeSource, type KnowledgeTool, type KnowledgeToolParams, type KnowledgeToolResult, MarkdownSource, type MarkdownSourceOptions, MemoryProvider, type MemoryProviderOptions, type MetadataFilter, OllamaEmbedder, type OllamaEmbedderOptions, OpenAIEmbedder, type OpenAIEmbedderOptions, OpenRouterEmbedder, type OpenRouterEmbedderOptions, PersistentKnowledgeProvider, type PersistentKnowledgeProviderOptions, PostgresSource, type PostgresSourceOptions, type QueryOptions, type QueryResult, SQLiteSource, type SQLiteSourceOptions, type SyncEvent, type SyncEventHandler, TextSource, type TextSourceOptions, VertexAIEmbedder, type VertexAIEmbedderOptions, WebUrlSource, type WebUrlSourceOptions, combineScores, keywordSearch, matchesFilter };

package/dist/index.d.ts

@@ -101,6 +101,8 @@ interface KnowledgeOptions {
     onError?: ErrorHandler;
     onSync?: SyncEventHandler;
     onEmbeddingProgress?: EmbeddingProgressHandler;
+    onAdd?: KnowledgeAddHandler;
+    onDelete?: KnowledgeDeleteHandler;
     streamingBatchSize?: number;
 }
 type ErrorHandler = (error: Error, context: {
@@ -121,6 +123,17 @@ interface EmbeddingProgressEvent {
     percent: number;
 }
 type EmbeddingProgressHandler = (event: EmbeddingProgressEvent) => void;
+interface KnowledgeAddEvent {
+    id: string;
+    content: string;
+    metadata: Record<string, unknown>;
+}
+type KnowledgeAddHandler = (event: KnowledgeAddEvent) => void;
+interface KnowledgeDeleteEvent {
+    ids: string[];
+    filter?: MetadataFilter;
+}
+type KnowledgeDeleteHandler = (event: KnowledgeDeleteEvent) => void;
 declare class Knowledge {
     private provider;
     private embedder;
@@ -144,6 +157,21 @@ declare class Knowledge {
      * @returns The ID of the added chunk
      */
     add(content: string, metadata?: Record<string, unknown>): Promise<string>;
+    /**
+     * Embeds and stores all chunks from a source without clearing existing data.
+     * Use this for adding or updating individual items in a persistent store.
+     * Returns the number of chunks ingested.
+     */
+    ingest(source: KnowledgeSource): Promise<number>;
+    delete(ids: string[]): Promise<void>;
+    /**
+     * Deletes all chunks whose metadata matches every key-value pair in the
+     * filter. Returns the IDs of the deleted chunks.
+     *
+     * Useful for cascade-deleting all chunks that belong to a platform item:
+     *   `knowledge.deleteWhere({ knowledge_item_id: "abc" })`
+     */
+    deleteWhere(filter: MetadataFilter): Promise<string[]>;
     stop(): Promise<void>;
     toTool(): KnowledgeTool;
 }
@@ -257,6 +285,22 @@ declare class MarkdownSource implements KnowledgeSource {
     private generateChunkId;
 }
 
+interface TextSourceOptions {
+    maxChunkSize?: number;
+    chunkOverlap?: number;
+    namespace?: string;
+    metadata?: Record<string, unknown>;
+}
+declare class TextSource implements KnowledgeSource {
+    private name;
+    private content;
+    private options;
+    constructor(name: string, content: string, options?: TextSourceOptions);
+    load(): AsyncIterable<Chunk>;
+    private chunkText;
+    private chunkId;
+}
+
 interface WebUrlSourceOptions {
     maxChunkSize?: number;
     chunkOverlap?: number;
@@ -470,6 +514,12 @@ interface VertexAIEmbedderOptions {
      * Example: 500 adds a 0.5s pause between batches (120 QPM effective rate).
      */
     rateLimitMs?: number;
+    /**
+     * Inline service account credentials object (parsed JSON key).
+     * When provided, used instead of Application Default Credentials.
+     * Mirrors the googleAuthOptions.credentials pattern in VertexAIAdapter.
+     */
+    credentials?: Record<string, unknown>;
 }
 declare class VertexAIEmbedder implements Embedder {
     readonly dimensions: number;
@@ -480,6 +530,7 @@ declare class VertexAIEmbedder implements Embedder {
     private readonly retries;
     private readonly retryDelay;
     private readonly rateLimitMs;
+    private readonly credentials?;
     private lastEmbedAt;
     constructor(options?: VertexAIEmbedderOptions);
     embed(text: string): Promise<number[]>;
@@ -491,4 +542,6 @@ declare class VertexAIEmbedder implements Embedder {
 declare function keywordSearch(text: string, query: string): number;
 declare function combineScores(semanticScore: number, keywordScore: number, semanticWeight?: number): number;
 
-export { ApiDataSource, type ApiDataSourceOptions, type Chunk, ChunkTooLargeError, type ChunkUpdate, DimensionMismatchError, type Embedder, EmbeddingError, type EmbeddingProgressEvent, type EmbeddingProgressHandler, type ErrorHandler, IngestionError, JSONSource, type JSONSourceOptions, Knowledge, KnowledgeError, type KnowledgeOptions, type KnowledgeProvider, KnowledgeProviderError, type KnowledgeSource, type KnowledgeTool, type KnowledgeToolParams, type KnowledgeToolResult, MarkdownSource, type MarkdownSourceOptions, MemoryProvider, type MemoryProviderOptions, type MetadataFilter, OllamaEmbedder, type OllamaEmbedderOptions, OpenAIEmbedder, type OpenAIEmbedderOptions, OpenRouterEmbedder, type OpenRouterEmbedderOptions, PersistentKnowledgeProvider, type PersistentKnowledgeProviderOptions, PostgresSource, type PostgresSourceOptions, type QueryOptions, type QueryResult, SQLiteSource, type SQLiteSourceOptions, type SyncEvent, type SyncEventHandler, VertexAIEmbedder, type VertexAIEmbedderOptions, WebUrlSource, type WebUrlSourceOptions, combineScores, keywordSearch };
+declare function matchesFilter(metadata: Record<string, unknown>, filter?: MetadataFilter): boolean;
+
+export { ApiDataSource, type ApiDataSourceOptions, type Chunk, ChunkTooLargeError, type ChunkUpdate, DimensionMismatchError, type Embedder, EmbeddingError, type EmbeddingProgressEvent, type EmbeddingProgressHandler, type ErrorHandler, IngestionError, JSONSource, type JSONSourceOptions, Knowledge, type KnowledgeAddEvent, type KnowledgeAddHandler, type KnowledgeDeleteEvent, type KnowledgeDeleteHandler, KnowledgeError, type KnowledgeOptions, type KnowledgeProvider, KnowledgeProviderError, type KnowledgeSource, type KnowledgeTool, type KnowledgeToolParams, type KnowledgeToolResult, MarkdownSource, type MarkdownSourceOptions, MemoryProvider, type MemoryProviderOptions, type MetadataFilter, OllamaEmbedder, type OllamaEmbedderOptions, OpenAIEmbedder, type OpenAIEmbedderOptions, OpenRouterEmbedder, type OpenRouterEmbedderOptions, PersistentKnowledgeProvider, type PersistentKnowledgeProviderOptions, PostgresSource, type PostgresSourceOptions, type QueryOptions, type QueryResult, SQLiteSource, type SQLiteSourceOptions, type SyncEvent, type SyncEventHandler, TextSource, type TextSourceOptions, VertexAIEmbedder, type VertexAIEmbedderOptions, WebUrlSource, type WebUrlSourceOptions, combineScores, keywordSearch, matchesFilter };