@toolpack-sdk/knowledge 1.2.0-SNAPSHOT.04032026-2

package/README.md

@@ -0,0 +1,220 @@
+# toolpack-knowledge
+
+RAG (Retrieval-Augmented Generation) package for Toolpack SDK.
+
+## Installation
+
+```bash
+npm install toolpack-knowledge
+```
+
+## Quick Start
+
+### Development (Zero Infrastructure)
+
+```typescript
+import { Knowledge, MemoryProvider, MarkdownSource, OllamaEmbedder } from 'toolpack-knowledge';
+
+const kb = await Knowledge.create({
+  provider: new MemoryProvider(),
+  sources: [new MarkdownSource('./docs/**/*.md')],
+  embedder: new OllamaEmbedder({ model: 'nomic-embed-text' }),
+  description: 'SDK documentation — setup guides, API reference, and examples.',
+});
+
+const results = await kb.query('how to install');
+console.log(results[0].chunk.content);
+```
+
+### Production (Persistent)
+
+```typescript
+import { Knowledge, PersistentKnowledgeProvider, MarkdownSource, OpenAIEmbedder } from 'toolpack-knowledge';
+
+const kb = await Knowledge.create({
+  provider: new PersistentKnowledgeProvider({
+    namespace: 'cli',
+    reSync: false,  // Load from disk if already indexed
+  }),
+  sources: [new MarkdownSource('./docs/**/*.md')],
+  embedder: new OpenAIEmbedder({
+    model: 'text-embedding-3-small',
+    apiKey: process.env.OPENAI_API_KEY!,
+  }),
+  description: 'CLI documentation and guides.',
+  onEmbeddingProgress: (event) => {
+    console.log(`Embedding: ${event.percent}% (${event.current}/${event.total})`);
+  },
+});
+
+const results = await kb.query('authentication setup', {
+  limit: 5,
+  threshold: 0.8,
+  filter: { hasCode: true },
+});
+```
+
+### Agent Integration
+
+```typescript
+import { Toolpack } from 'toolpack-sdk';
+import { Knowledge, MemoryProvider, MarkdownSource, OllamaEmbedder } from 'toolpack-knowledge';
+
+const kb = await Knowledge.create({
+  provider: new MemoryProvider(),
+  sources: [new MarkdownSource('./docs/**/*.md')],
+  embedder: new OllamaEmbedder({ model: 'nomic-embed-text' }),
+  description: 'Search this when the user asks about setup, configuration, or API usage.',
+});
+
+const toolpack = await Toolpack.init({
+  provider: 'anthropic',
+  knowledge: kb,  // Registered as knowledge_search tool
+});
+
+const response = await toolpack.chat('How do I configure authentication?');
+```
+
+## Providers
+
+### MemoryProvider
+
+In-memory vector storage. Zero configuration, perfect for development and prototyping.
+
+```typescript
+new MemoryProvider({
+  maxChunks: 10000,  // Optional limit
+})
+```
+
+### PersistentKnowledgeProvider
+
+SQLite-backed persistence for CLI tools and desktop apps.
+
+```typescript
+new PersistentKnowledgeProvider({
+  namespace: 'my-app',           // Creates ~/.toolpack/knowledge/my-app.db
+  storagePath: './custom/path',  // Optional: override storage location
+  reSync: false,                 // Optional: skip re-indexing if DB exists
+})
+```
+
+## Sources
+
+### MarkdownSource
+
+Chunks markdown files by heading hierarchy.
+
+```typescript
+new MarkdownSource('./docs/**/*.md', {
+  maxChunkSize: 2000,      // Max tokens per chunk
+  chunkOverlap: 200,       // Overlap between chunks
+  minChunkSize: 100,       // Merge small sections
+  namespace: 'docs',       // Prefix for chunk IDs
+  metadata: { type: 'documentation' },  // Added to all chunks
+})
+```
+
+**Features:**
+- Heading-based chunking (preserves document structure)
+- Frontmatter extraction (YAML)
+- Code block detection (`hasCode` metadata)
+- Deterministic chunk IDs
+
+## Embedders
+
+### OllamaEmbedder
+
+Local embeddings via Ollama. Zero API cost.
+
+```typescript
+new OllamaEmbedder({
+  model: 'nomic-embed-text',           // or 'mxbai-embed-large'
+  baseUrl: 'http://localhost:11434',   // default
+})
+```
+
+### OpenAIEmbedder
+
+OpenAI text-embedding models with retry logic.
+
+```typescript
+new OpenAIEmbedder({
+  model: 'text-embedding-3-small',    // or 'text-embedding-3-large'
+  apiKey: process.env.OPENAI_API_KEY,
+  retries: 3,                         // default
+  retryDelay: 1000,                   // ms, default
+  timeout: 30000,                     // ms, default
+})
+```
+
+## API Reference
+
+### Knowledge.create()
+
+```typescript
+interface KnowledgeOptions {
+  provider: KnowledgeProvider;
+  sources: KnowledgeSource[];
+  embedder: Embedder;
+  description: string;                        // Required: used as tool description
+  reSync?: boolean;                           // default: true
+  onError?: (error, context) => 'skip' | 'abort';
+  onSync?: (event: SyncEvent) => void;
+  onEmbeddingProgress?: (event: EmbeddingProgressEvent) => void;
+}
+```
+
+### query()
+
+```typescript
+await kb.query('search query', {
+  limit: 10,              // Max results
+  threshold: 0.7,         // Similarity threshold (0-1)
+  filter: {               // Metadata filters
+    hasCode: true,
+    category: { $in: ['api', 'guide'] },
+  },
+  includeMetadata: true,  // default
+  includeVectors: false,  // default
+});
+```
+
+### Metadata Filters
+
+```typescript
+{
+  field: 'value',                    // Exact match
+  field: { $in: ['a', 'b'] },       // In array
+  field: { $gt: 100 },              // Greater than
+  field: { $lt: 100 },              // Less than
+}
+```
+
+## Error Handling
+
+```typescript
+const kb = await Knowledge.create({
+  // ...
+  onError: (error, context) => {
+    console.error(`Failed: ${context.file} — ${error.message}`);
+    
+    if (error instanceof EmbeddingError) {
+      return 'skip';  // Skip this chunk, continue
+    }
+    return 'abort';   // Stop ingestion
+  },
+});
+```
+
+**Error Types:**
+- `KnowledgeError` — Base class
+- `EmbeddingError` — Embedding API failure
+- `IngestionError` — Source file parsing failure
+- `ChunkTooLargeError` — Chunk exceeds max size
+- `DimensionMismatchError` — Embedder dimensions mismatch
+- `KnowledgeProviderError` — Provider operation failure
+
+## License
+
+Apache-2.0

package/dist/embedders/ollama.d.ts

@@ -0,0 +1,15 @@
+import { Embedder } from '../interfaces.js';
+export interface OllamaEmbedderOptions {
+    model: string;
+    baseUrl?: string;
+}
+export declare class OllamaEmbedder implements Embedder {
+    private options;
+    readonly dimensions: number;
+    private baseUrl;
+    constructor(options: OllamaEmbedderOptions);
+    private getModelDimensions;
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+}
+//# sourceMappingURL=ollama.d.ts.map

package/dist/embedders/ollama.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ollama.d.ts","sourceRoot":"","sources":["../../src/embedders/ollama.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAG5C,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,cAAe,YAAW,QAAQ;IAIjC,OAAO,CAAC,OAAO;IAH3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,OAAO,CAAS;gBAEJ,OAAO,EAAE,qBAAqB;IAKlD,OAAO,CAAC,kBAAkB;IASpB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAsBtC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;CAOvD"}

package/dist/embedders/ollama.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OllamaEmbedder = void 0;
+const errors_js_1 = require("../errors.js");
+class OllamaEmbedder {
+    options;
+    dimensions;
+    baseUrl;
+    constructor(options) {
+        this.options = options;
+        this.baseUrl = options.baseUrl || 'http://localhost:11434';
+        this.dimensions = this.getModelDimensions(options.model);
+    }
+    getModelDimensions(model) {
+        const dimensionsMap = {
+            'nomic-embed-text': 768,
+            'mxbai-embed-large': 1024,
+            'all-minilm': 384,
+        };
+        return dimensionsMap[model] || 768;
+    }
+    async embed(text) {
+        try {
+            const response = await fetch(`${this.baseUrl}/api/embeddings`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ model: this.options.model, prompt: text }),
+            });
+            if (!response.ok) {
+                throw new errors_js_1.EmbeddingError(`Ollama embedding failed: ${response.statusText}`, response.status);
+            }
+            const data = await response.json();
+            return data.embedding;
+        }
+        catch (error) {
+            if (error instanceof errors_js_1.EmbeddingError) {
+                throw error;
+            }
+            throw new errors_js_1.EmbeddingError(`Ollama embedding failed: ${error.message}`);
+        }
+    }
+    async embedBatch(texts) {
+        const embeddings = [];
+        for (const text of texts) {
+            embeddings.push(await this.embed(text));
+        }
+        return embeddings;
+    }
+}
+exports.OllamaEmbedder = OllamaEmbedder;
+//# sourceMappingURL=ollama.js.map

package/dist/embedders/ollama.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ollama.js","sourceRoot":"","sources":["../../src/embedders/ollama.ts"],"names":[],"mappings":";;;AACA,4CAA8C;AAO9C,MAAa,cAAc;IAIL;IAHX,UAAU,CAAS;IACpB,OAAO,CAAS;IAExB,YAAoB,OAA8B;QAA9B,YAAO,GAAP,OAAO,CAAuB;QAChD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,wBAAwB,CAAC;QAC3D,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3D,CAAC;IAEO,kBAAkB,CAAC,KAAa;QACtC,MAAM,aAAa,GAA2B;YAC5C,kBAAkB,EAAE,GAAG;YACvB,mBAAmB,EAAE,IAAI;YACzB,YAAY,EAAE,GAAG;SAClB,CAAC;QACF,OAAO,aAAa,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,iBAAiB,EAAE;gBAC7D,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;aAClE,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,0BAAc,CAAC,4BAA4B,QAAQ,CAAC,UAAU,EAAE,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC/F,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAA6B,CAAC;YAC9D,OAAO,IAAI,CAAC,SAAS,CAAC;QACxB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,0BAAc,EAAE,CAAC;gBACpC,MAAM,KAAK,CAAC;YACd,CAAC;YACD,MAAM,IAAI,0BAAc,CAAC,4BAA6B,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QACnF,CAAC;IACH,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,KAAe;QAC9B,MAAM,UAAU,GAAe,EAAE,CAAC;QAClC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,UAAU,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QAC1C,CAAC;QACD,OAAO,UAAU,CAAC;IACpB,CAAC;CACF;AA/CD,wCA+CC"}

package/dist/embedders/openai.d.ts

@@ -0,0 +1,18 @@
+import { Embedder } from '../interfaces.js';
+export interface OpenAIEmbedderOptions {
+    model: string;
+    apiKey: string;
+    retries?: number;
+    retryDelay?: number;
+    timeout?: number;
+}
+export declare class OpenAIEmbedder implements Embedder {
+    private options;
+    readonly dimensions: number;
+    private client;
+    constructor(options: OpenAIEmbedderOptions);
+    private getModelDimensions;
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+}
+//# sourceMappingURL=openai.d.ts.map

package/dist/embedders/openai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/embedders/openai.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAG5C,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,cAAe,YAAW,QAAQ;IAIjC,OAAO,CAAC,OAAO;IAH3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,MAAM,CAAS;gBAEH,OAAO,EAAE,qBAAqB;IAQlD,OAAO,CAAC,kBAAkB;IASpB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAsBtC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;CAWvD"}

package/dist/embedders/openai.js

@@ -0,0 +1,63 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAIEmbedder = void 0;
+const openai_1 = __importDefault(require("openai"));
+const errors_js_1 = require("../errors.js");
+class OpenAIEmbedder {
+    options;
+    dimensions;
+    client;
+    constructor(options) {
+        this.options = options;
+        this.client = new openai_1.default({
+            apiKey: options.apiKey,
+            timeout: options.timeout || 30000,
+        });
+        this.dimensions = this.getModelDimensions(options.model);
+    }
+    getModelDimensions(model) {
+        const dimensionsMap = {
+            'text-embedding-3-small': 1536,
+            'text-embedding-3-large': 3072,
+            'text-embedding-ada-002': 1536,
+        };
+        return dimensionsMap[model] || 1536;
+    }
+    async embed(text) {
+        let lastError = null;
+        const retries = this.options.retries || 3;
+        for (let attempt = 0; attempt < retries; attempt++) {
+            try {
+                const response = await this.client.embeddings.create({
+                    model: this.options.model,
+                    input: text,
+                });
+                return response.data[0].embedding;
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt < retries - 1) {
+                    await new Promise(resolve => setTimeout(resolve, this.options.retryDelay || 1000));
+                }
+            }
+        }
+        throw new errors_js_1.EmbeddingError(`OpenAI embedding failed after ${retries} retries: ${lastError?.message}`);
+    }
+    async embedBatch(texts) {
+        try {
+            const response = await this.client.embeddings.create({
+                model: this.options.model,
+                input: texts,
+            });
+            return response.data.map(d => d.embedding);
+        }
+        catch (error) {
+            throw new errors_js_1.EmbeddingError(`OpenAI batch embedding failed: ${error.message}`);
+        }
+    }
+}
+exports.OpenAIEmbedder = OpenAIEmbedder;
+//# sourceMappingURL=openai.js.map

package/dist/embedders/openai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/embedders/openai.ts"],"names":[],"mappings":";;;;;;AAAA,oDAA4B;AAE5B,4CAA8C;AAU9C,MAAa,cAAc;IAIL;IAHX,UAAU,CAAS;IACpB,MAAM,CAAS;IAEvB,YAAoB,OAA8B;QAA9B,YAAO,GAAP,OAAO,CAAuB;QAChD,IAAI,CAAC,MAAM,GAAG,IAAI,gBAAM,CAAC;YACvB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,KAAK;SAClC,CAAC,CAAC;QACH,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3D,CAAC;IAEO,kBAAkB,CAAC,KAAa;QACtC,MAAM,aAAa,GAA2B;YAC5C,wBAAwB,EAAE,IAAI;YAC9B,wBAAwB,EAAE,IAAI;YAC9B,wBAAwB,EAAE,IAAI;SAC/B,CAAC;QACF,OAAO,aAAa,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC;IACtC,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,IAAI,SAAS,GAAiB,IAAI,CAAC;QACnC,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC;QAE1C,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC;YACnD,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;oBACnD,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK;oBACzB,KAAK,EAAE,IAAI;iBACZ,CAAC,CAAC;gBACH,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACpC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,SAAS,GAAG,KAAc,CAAC;gBAC3B,IAAI,OAAO,GAAG,OAAO,GAAG,CAAC,EAAE,CAAC;oBAC1B,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC,CAAC,CAAC;gBACrF,CAAC;YACH,CAAC;QACH,CAAC;QAED,MAAM,IAAI,0BAAc,CAAC,iCAAiC,OAAO,aAAa,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC;IACtG,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,KAAe;QAC9B,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;gBACnD,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK;gBACzB,KAAK,EAAE,KAAK;aACb,CAAC,CAAC;YACH,OAAO,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAC7C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,0BAAc,CAAC,kCAAmC,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QACzF,CAAC;IACH,CAAC;CACF;AAtDD,wCAsDC"}

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+export declare class KnowledgeError extends Error {
+    readonly code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
+}
+export declare class EmbeddingError extends KnowledgeError {
+    readonly statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined);
+}
+export declare class IngestionError extends KnowledgeError {
+    readonly file?: string | undefined;
+    constructor(message: string, file?: string | undefined);
+}
+export declare class ChunkTooLargeError extends KnowledgeError {
+    readonly chunkSize: number;
+    constructor(message: string, chunkSize: number);
+}
+export declare class DimensionMismatchError extends KnowledgeError {
+    readonly expected: number;
+    readonly actual: number;
+    constructor(expected: number, actual: number);
+}
+export declare class KnowledgeProviderError extends KnowledgeError {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,cAAe,SAAQ,KAAK;aACM,IAAI,CAAC,EAAE,MAAM;gBAA9C,OAAO,EAAE,MAAM,EAAkB,IAAI,CAAC,EAAE,MAAM,YAAA;CAI3D;AAED,qBAAa,cAAe,SAAQ,cAAc;aACH,UAAU,CAAC,EAAE,MAAM;gBAApD,OAAO,EAAE,MAAM,EAAkB,UAAU,CAAC,EAAE,MAAM,YAAA;CAIjE;AAED,qBAAa,cAAe,SAAQ,cAAc;aACH,IAAI,CAAC,EAAE,MAAM;gBAA9C,OAAO,EAAE,MAAM,EAAkB,IAAI,CAAC,EAAE,MAAM,YAAA;CAI3D;AAED,qBAAa,kBAAmB,SAAQ,cAAc;aACP,SAAS,EAAE,MAAM;gBAAlD,OAAO,EAAE,MAAM,EAAkB,SAAS,EAAE,MAAM;CAI/D;AAED,qBAAa,sBAAuB,SAAQ,cAAc;IACxD,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,MAAM,EAAE,MAAM,CAAC;gBAEnB,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAS7C;AAED,qBAAa,sBAAuB,SAAQ,cAAc;gBAC5C,OAAO,EAAE,MAAM;CAI5B"}

package/dist/errors.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KnowledgeProviderError = exports.DimensionMismatchError = exports.ChunkTooLargeError = exports.IngestionError = exports.EmbeddingError = exports.KnowledgeError = void 0;
+class KnowledgeError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'KnowledgeError';
+    }
+}
+exports.KnowledgeError = KnowledgeError;
+class EmbeddingError extends KnowledgeError {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message, 'EMBEDDING_ERROR');
+        this.statusCode = statusCode;
+        this.name = 'EmbeddingError';
+    }
+}
+exports.EmbeddingError = EmbeddingError;
+class IngestionError extends KnowledgeError {
+    file;
+    constructor(message, file) {
+        super(message, 'INGESTION_ERROR');
+        this.file = file;
+        this.name = 'IngestionError';
+    }
+}
+exports.IngestionError = IngestionError;
+class ChunkTooLargeError extends KnowledgeError {
+    chunkSize;
+    constructor(message, chunkSize) {
+        super(message, 'CHUNK_TOO_LARGE');
+        this.chunkSize = chunkSize;
+        this.name = 'ChunkTooLargeError';
+    }
+}
+exports.ChunkTooLargeError = ChunkTooLargeError;
+class DimensionMismatchError extends KnowledgeError {
+    expected;
+    actual;
+    constructor(expected, actual) {
+        super(`Dimension mismatch: expected ${expected}, got ${actual}`, 'DIMENSION_MISMATCH');
+        this.name = 'DimensionMismatchError';
+        this.expected = expected;
+        this.actual = actual;
+    }
+}
+exports.DimensionMismatchError = DimensionMismatchError;
+class KnowledgeProviderError extends KnowledgeError {
+    constructor(message) {
+        super(message, 'PROVIDER_ERROR');
+        this.name = 'KnowledgeProviderError';
+    }
+}
+exports.KnowledgeProviderError = KnowledgeProviderError;
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";;;AAAA,MAAa,cAAe,SAAQ,KAAK;IACM;IAA7C,YAAY,OAAe,EAAkB,IAAa;QACxD,KAAK,CAAC,OAAO,CAAC,CAAC;QAD4B,SAAI,GAAJ,IAAI,CAAS;QAExD,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AALD,wCAKC;AAED,MAAa,cAAe,SAAQ,cAAc;IACH;IAA7C,YAAY,OAAe,EAAkB,UAAmB;QAC9D,KAAK,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;QADS,eAAU,GAAV,UAAU,CAAS;QAE9D,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AALD,wCAKC;AAED,MAAa,cAAe,SAAQ,cAAc;IACH;IAA7C,YAAY,OAAe,EAAkB,IAAa;QACxD,KAAK,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;QADS,SAAI,GAAJ,IAAI,CAAS;QAExD,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AALD,wCAKC;AAED,MAAa,kBAAmB,SAAQ,cAAc;IACP;IAA7C,YAAY,OAAe,EAAkB,SAAiB;QAC5D,KAAK,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;QADS,cAAS,GAAT,SAAS,CAAQ;QAE5D,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AALD,gDAKC;AAED,MAAa,sBAAuB,SAAQ,cAAc;IACxC,QAAQ,CAAS;IACjB,MAAM,CAAS;IAE/B,YAAY,QAAgB,EAAE,MAAc;QAC1C,KAAK,CACH,gCAAgC,QAAQ,SAAS,MAAM,EAAE,EACzD,oBAAoB,CACrB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAbD,wDAaC;AAED,MAAa,sBAAuB,SAAQ,cAAc;IACxD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AALD,wDAKC"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export * from './interfaces.js';
+export * from './errors.js';
+export * from './knowledge.js';
+export { MemoryProvider } from './providers/memory.js';
+export type { MemoryProviderOptions } from './providers/memory.js';
+export { PersistentKnowledgeProvider } from './providers/persistent.js';
+export type { PersistentKnowledgeProviderOptions } from './providers/persistent.js';
+export { MarkdownSource } from './sources/markdown.js';
+export type { MarkdownSourceOptions } from './sources/markdown.js';
+export { OllamaEmbedder } from './embedders/ollama.js';
+export type { OllamaEmbedderOptions } from './embedders/ollama.js';
+export { OpenAIEmbedder } from './embedders/openai.js';
+export type { OpenAIEmbedderOptions } from './embedders/openai.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAE/B,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAEnE,OAAO,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AACxE,YAAY,EAAE,kCAAkC,EAAE,MAAM,2BAA2B,CAAC;AAEpF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAEnE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAEnE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,31 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAIEmbedder = exports.OllamaEmbedder = exports.MarkdownSource = exports.PersistentKnowledgeProvider = exports.MemoryProvider = void 0;
+__exportStar(require("./interfaces.js"), exports);
+__exportStar(require("./errors.js"), exports);
+__exportStar(require("./knowledge.js"), exports);
+var memory_js_1 = require("./providers/memory.js");
+Object.defineProperty(exports, "MemoryProvider", { enumerable: true, get: function () { return memory_js_1.MemoryProvider; } });
+var persistent_js_1 = require("./providers/persistent.js");
+Object.defineProperty(exports, "PersistentKnowledgeProvider", { enumerable: true, get: function () { return persistent_js_1.PersistentKnowledgeProvider; } });
+var markdown_js_1 = require("./sources/markdown.js");
+Object.defineProperty(exports, "MarkdownSource", { enumerable: true, get: function () { return markdown_js_1.MarkdownSource; } });
+var ollama_js_1 = require("./embedders/ollama.js");
+Object.defineProperty(exports, "OllamaEmbedder", { enumerable: true, get: function () { return ollama_js_1.OllamaEmbedder; } });
+var openai_js_1 = require("./embedders/openai.js");
+Object.defineProperty(exports, "OpenAIEmbedder", { enumerable: true, get: function () { return openai_js_1.OpenAIEmbedder; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,kDAAgC;AAChC,8CAA4B;AAC5B,iDAA+B;AAE/B,mDAAuD;AAA9C,2GAAA,cAAc,OAAA;AAGvB,2DAAwE;AAA/D,4HAAA,2BAA2B,OAAA;AAGpC,qDAAuD;AAA9C,6GAAA,cAAc,OAAA;AAGvB,mDAAuD;AAA9C,2GAAA,cAAc,OAAA;AAGvB,mDAAuD;AAA9C,2GAAA,cAAc,OAAA"}

package/dist/interfaces.d.ts

@@ -0,0 +1,48 @@
+export interface Chunk {
+    id: string;
+    content: string;
+    metadata: Record<string, unknown>;
+    vector?: number[];
+}
+export interface ChunkUpdate {
+    type: 'add' | 'update' | 'delete';
+    chunk: Chunk;
+}
+export interface QueryOptions {
+    limit?: number;
+    threshold?: number;
+    filter?: MetadataFilter;
+    includeMetadata?: boolean;
+    includeVectors?: boolean;
+}
+export interface MetadataFilter {
+    [key: string]: string | number | boolean | {
+        $in: unknown[];
+    } | {
+        $gt: number;
+    } | {
+        $lt: number;
+    };
+}
+export interface QueryResult {
+    chunk: Chunk;
+    score: number;
+    distance?: number;
+}
+export interface KnowledgeProvider {
+    add(chunks: Chunk[]): Promise<void>;
+    query(queryVector: number[], options?: QueryOptions): Promise<QueryResult[]>;
+    delete(ids: string[]): Promise<void>;
+    clear(): Promise<void>;
+    validateDimensions(dimensions: number): Promise<void>;
+}
+export interface KnowledgeSource {
+    load(): AsyncIterable<Chunk>;
+    watch?(): AsyncIterable<ChunkUpdate>;
+}
+export interface Embedder {
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+    readonly dimensions: number;
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAClC,KAAK,EAAE,KAAK,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GACpC;QAAE,GAAG,EAAE,OAAO,EAAE,CAAA;KAAE,GAClB;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GACf;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC7E,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,IAAI,aAAa,CAAC,KAAK,CAAC,CAAC;IAC7B,KAAK,CAAC,IAAI,aAAa,CAAC,WAAW,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACvC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B"}

package/dist/interfaces.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=interfaces.js.map

package/dist/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":""}