@toolpack-sdk/knowledge 1.4.0 → 2.0.0

package/dist/index.d.cts

@@ -120,6 +120,14 @@ declare class Knowledge {
     private getAllChunks;
     sync(): Promise<void>;
     private embedChunks;
+    /**
+     * Add a single content item to the knowledge base without triggering a full re-sync.
+     * This is useful for runtime additions like conversation history or agent state.
+     * @param content The text content to add
+     * @param metadata Optional metadata to attach to the chunk
+     * @returns The ID of the added chunk
+     */
+    add(content: string, metadata?: Record<string, unknown>): Promise<string>;
     stop(): Promise<void>;
     toTool(): KnowledgeTool;
 }
@@ -276,6 +284,78 @@ declare class ApiDataSource implements KnowledgeSource {
     private generateChunkId;
 }
 
+interface JSONSourceOptions {
+    namespace?: string;
+    metadata?: Record<string, unknown>;
+    filter?: (item: unknown) => boolean;
+    chunkSize?: number;
+    /** Required. Transform each JSON item into a human-readable string for AI embedding. */
+    toContent: (item: unknown) => string;
+}
+/**
+ * Knowledge source for JSON files.
+ * Supports jq-like filtering and chunking of large arrays.
+ */
+declare class JSONSource implements KnowledgeSource {
+    private filePath;
+    private options;
+    constructor(filePath: string, options: JSONSourceOptions);
+    load(): AsyncIterable<Chunk>;
+}
+
+interface SQLiteSourceOptions {
+    namespace?: string;
+    metadata?: Record<string, unknown>;
+    query?: string;
+    chunkSize?: number;
+    /** Required. Transform each database row into a human-readable string for AI embedding. */
+    toContent: (row: Record<string, unknown>) => string;
+    preLoadCSV?: {
+        tableName: string;
+        csvPath: string;
+        delimiter?: string;
+        headers?: boolean;
+    };
+}
+/**
+ * Knowledge source for SQLite databases.
+ * Supports SQL queries and optional CSV/TSV pre-loading.
+ * Note: This requires the 'better-sqlite3' package to be installed.
+ */
+declare class SQLiteSource implements KnowledgeSource {
+    private dbPath;
+    private options;
+    constructor(dbPath: string, options: SQLiteSourceOptions);
+    load(): AsyncIterable<Chunk>;
+    private loadCSV;
+}
+
+interface PostgresSourceOptions {
+    namespace?: string;
+    metadata?: Record<string, unknown>;
+    query: string;
+    chunkSize?: number;
+    /** Required. Transform each database row into a human-readable string for AI embedding. */
+    toContent: (row: Record<string, unknown>) => string;
+    connectionString?: string;
+    host?: string;
+    port?: number;
+    database?: string;
+    user?: string;
+    password?: string;
+    ssl?: boolean;
+}
+/**
+ * Knowledge source for PostgreSQL databases.
+ * Supports SQL queries with optional chunking.
+ * Note: This requires the 'pg' package to be installed.
+ */
+declare class PostgresSource implements KnowledgeSource {
+    private options;
+    constructor(options: PostgresSourceOptions);
+    load(): AsyncIterable<Chunk>;
+}
+
 interface OllamaEmbedderOptions {
     model: string;
     baseUrl?: string;
@@ -311,7 +391,61 @@ declare class OpenAIEmbedder implements Embedder {
     embedBatch(texts: string[]): Promise<number[][]>;
 }
 
+interface OpenRouterEmbedderOptions {
+    model: string;
+    apiKey: string;
+    /** Override output dimensions for models not in the built-in map */
+    dimensions?: number;
+    retries?: number;
+    retryDelay?: number;
+    timeout?: number;
+}
+declare class OpenRouterEmbedder implements Embedder {
+    private options;
+    readonly dimensions: number;
+    private client;
+    constructor(options: OpenRouterEmbedderOptions);
+    private getModelDimensions;
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+}
+
+interface VertexAIEmbedderOptions {
+    /** GCP project ID. Falls back to VERTEX_AI_PROJECT / GOOGLE_CLOUD_PROJECT env vars. */
+    projectId?: string;
+    /** GCP region. Defaults to 'us-central1'. */
+    location?: string;
+    /**
+     * Embedding model. Defaults to 'gemini-embedding-2' (3072 dims).
+     * Other options: 'gemini-embedding-001' (3072), 'text-embedding-005' (768).
+     */
+    model?: string;
+    /**
+     * Output dimensionality override.
+     * Must match what the knowledge store was initialised with — changing this requires wiping the store.
+     */
+    outputDimensionality?: number;
+    /** Max retries on transient errors. Default: 3. */
+    retries?: number;
+    /** Delay between retries in ms. Default: 1000. */
+    retryDelay?: number;
+}
+declare class VertexAIEmbedder implements Embedder {
+    readonly dimensions: number;
+    private readonly projectId;
+    private readonly location;
+    private readonly model;
+    private readonly outputDimensionality;
+    private readonly retries;
+    private readonly retryDelay;
+    constructor(options?: VertexAIEmbedderOptions);
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+    private _request;
+    private _getAccessToken;
+}
+
 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, 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, PersistentKnowledgeProvider, type PersistentKnowledgeProviderOptions, type QueryOptions, type QueryResult, type SyncEvent, type SyncEventHandler, WebUrlSource, type WebUrlSourceOptions, combineScores, keywordSearch };
+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 };

package/dist/index.d.ts

@@ -120,6 +120,14 @@ declare class Knowledge {
     private getAllChunks;
     sync(): Promise<void>;
     private embedChunks;
+    /**
+     * Add a single content item to the knowledge base without triggering a full re-sync.
+     * This is useful for runtime additions like conversation history or agent state.
+     * @param content The text content to add
+     * @param metadata Optional metadata to attach to the chunk
+     * @returns The ID of the added chunk
+     */
+    add(content: string, metadata?: Record<string, unknown>): Promise<string>;
     stop(): Promise<void>;
     toTool(): KnowledgeTool;
 }
@@ -276,6 +284,78 @@ declare class ApiDataSource implements KnowledgeSource {
     private generateChunkId;
 }
 
+interface JSONSourceOptions {
+    namespace?: string;
+    metadata?: Record<string, unknown>;
+    filter?: (item: unknown) => boolean;
+    chunkSize?: number;
+    /** Required. Transform each JSON item into a human-readable string for AI embedding. */
+    toContent: (item: unknown) => string;
+}
+/**
+ * Knowledge source for JSON files.
+ * Supports jq-like filtering and chunking of large arrays.
+ */
+declare class JSONSource implements KnowledgeSource {
+    private filePath;
+    private options;
+    constructor(filePath: string, options: JSONSourceOptions);
+    load(): AsyncIterable<Chunk>;
+}
+
+interface SQLiteSourceOptions {
+    namespace?: string;
+    metadata?: Record<string, unknown>;
+    query?: string;
+    chunkSize?: number;
+    /** Required. Transform each database row into a human-readable string for AI embedding. */
+    toContent: (row: Record<string, unknown>) => string;
+    preLoadCSV?: {
+        tableName: string;
+        csvPath: string;
+        delimiter?: string;
+        headers?: boolean;
+    };
+}
+/**
+ * Knowledge source for SQLite databases.
+ * Supports SQL queries and optional CSV/TSV pre-loading.
+ * Note: This requires the 'better-sqlite3' package to be installed.
+ */
+declare class SQLiteSource implements KnowledgeSource {
+    private dbPath;
+    private options;
+    constructor(dbPath: string, options: SQLiteSourceOptions);
+    load(): AsyncIterable<Chunk>;
+    private loadCSV;
+}
+
+interface PostgresSourceOptions {
+    namespace?: string;
+    metadata?: Record<string, unknown>;
+    query: string;
+    chunkSize?: number;
+    /** Required. Transform each database row into a human-readable string for AI embedding. */
+    toContent: (row: Record<string, unknown>) => string;
+    connectionString?: string;
+    host?: string;
+    port?: number;
+    database?: string;
+    user?: string;
+    password?: string;
+    ssl?: boolean;
+}
+/**
+ * Knowledge source for PostgreSQL databases.
+ * Supports SQL queries with optional chunking.
+ * Note: This requires the 'pg' package to be installed.
+ */
+declare class PostgresSource implements KnowledgeSource {
+    private options;
+    constructor(options: PostgresSourceOptions);
+    load(): AsyncIterable<Chunk>;
+}
+
 interface OllamaEmbedderOptions {
     model: string;
     baseUrl?: string;
@@ -311,7 +391,61 @@ declare class OpenAIEmbedder implements Embedder {
     embedBatch(texts: string[]): Promise<number[][]>;
 }
 
+interface OpenRouterEmbedderOptions {
+    model: string;
+    apiKey: string;
+    /** Override output dimensions for models not in the built-in map */
+    dimensions?: number;
+    retries?: number;
+    retryDelay?: number;
+    timeout?: number;
+}
+declare class OpenRouterEmbedder implements Embedder {
+    private options;
+    readonly dimensions: number;
+    private client;
+    constructor(options: OpenRouterEmbedderOptions);
+    private getModelDimensions;
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+}
+
+interface VertexAIEmbedderOptions {
+    /** GCP project ID. Falls back to VERTEX_AI_PROJECT / GOOGLE_CLOUD_PROJECT env vars. */
+    projectId?: string;
+    /** GCP region. Defaults to 'us-central1'. */
+    location?: string;
+    /**
+     * Embedding model. Defaults to 'gemini-embedding-2' (3072 dims).
+     * Other options: 'gemini-embedding-001' (3072), 'text-embedding-005' (768).
+     */
+    model?: string;
+    /**
+     * Output dimensionality override.
+     * Must match what the knowledge store was initialised with — changing this requires wiping the store.
+     */
+    outputDimensionality?: number;
+    /** Max retries on transient errors. Default: 3. */
+    retries?: number;
+    /** Delay between retries in ms. Default: 1000. */
+    retryDelay?: number;
+}
+declare class VertexAIEmbedder implements Embedder {
+    readonly dimensions: number;
+    private readonly projectId;
+    private readonly location;
+    private readonly model;
+    private readonly outputDimensionality;
+    private readonly retries;
+    private readonly retryDelay;
+    constructor(options?: VertexAIEmbedderOptions);
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+    private _request;
+    private _getAccessToken;
+}
+
 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, 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, PersistentKnowledgeProvider, type PersistentKnowledgeProviderOptions, type QueryOptions, type QueryResult, type SyncEvent, type SyncEventHandler, WebUrlSource, type WebUrlSourceOptions, combineScores, keywordSearch };
+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 };