maskweaver 0.9.3 → 0.9.5

package/dist/memory/providers/examples.js

@@ -1,20 +1,10 @@
-/**
- * Embedding Provider Usage Examples
- *
- * Practical examples showing how to use the provider system.
- */
 import { createProvider, selectBestProvider, getDefaultConfigs } from "./index.js";
-// ============================================================================
-// Example 1: Auto-selection (Recommended)
-// ============================================================================
 async function example1_autoSelection() {
     console.log("Example 1: Auto-selection with graceful degradation\n");
-    // Let the system choose the best available provider
     const provider = await selectBestProvider(getDefaultConfigs());
     console.log(`✓ Selected: ${provider.name}`);
     console.log(`  Type: ${provider.type}`);
     console.log(`  Dimensions: ${provider.dimensions}\n`);
-    // Use it!
     const embeddings = await provider.embed([
         "Hello, world!",
         "TypeScript is awesome"
@@ -22,18 +12,13 @@ async function example1_autoSelection() {
     console.log(`Generated ${embeddings.length} embeddings`);
     console.log(`Each embedding has ${embeddings[0].length} dimensions\n`);
 }
-// ============================================================================
-// Example 2: Manual Provider Selection
-// ============================================================================
 async function example2_manualSelection() {
     console.log("Example 2: Manual provider selection\n");
-    // For local development - privacy-first
     const localProvider = createProvider({
         type: "ollama",
         model: "nomic-embed-text"
     });
     console.log(`Using: ${localProvider.name}`);
-    // Check health before using
     const health = await localProvider.healthCheck();
     if (!health.ok) {
         console.error(`❌ ${health.reason}`);
@@ -46,9 +31,6 @@ async function example2_manualSelection() {
     const embeddings = await localProvider.embed(["Test document"]);
     console.log(`Generated embedding with ${embeddings[0].length} dimensions\n`);
 }
-// ============================================================================
-// Example 3: Code-Specialized Embedding
-// ============================================================================
 async function example3_codeEmbedding() {
     console.log("Example 3: Code-specialized embedding with Voyage\n");
     const codeProvider = createProvider({
@@ -57,22 +39,17 @@ async function example3_codeEmbedding() {
         dimensions: 1024,
         apiKey: process.env.VOYAGE_API_KEY
     });
-    // Code snippets
     const codeSnippets = [
         "function fibonacci(n: number): number { return n < 2 ? n : fibonacci(n-1) + fibonacci(n-2); }",
         "const factorial = (n: number): number => n <= 1 ? 1 : n * factorial(n - 1);",
         "class Stack<T> { private items: T[] = []; push(item: T) { this.items.push(item); } }"
     ];
-    // Use code-specific embedding
     if (codeProvider.embedCode) {
         const embeddings = await codeProvider.embedCode(codeSnippets);
         console.log(`Generated ${embeddings.length} code embeddings`);
         console.log(`Optimized for code similarity search\n`);
     }
 }
-// ============================================================================
-// Example 4: Asymmetric Search (Query vs Document)
-// ============================================================================
 async function example4_asymmetricSearch() {
     console.log("Example 4: Asymmetric search with Voyage\n");
     const provider = createProvider({
@@ -80,17 +57,13 @@ async function example4_asymmetricSearch() {
         model: "voyage-4-lite",
         apiKey: process.env.VOYAGE_API_KEY
     });
-    // Documents (what you're searching through)
     const documents = [
         "TypeScript is a strongly typed programming language that builds on JavaScript.",
         "Python is an interpreted, high-level programming language with dynamic semantics.",
         "Rust is a systems programming language focused on safety and performance."
     ];
-    // Query (what the user is searching for)
     const query = "What is a type-safe language?";
-    // Embed documents
     const docEmbeddings = await provider.embed(documents);
-    // Embed query (optimized differently)
     let queryEmbedding;
     if (provider.embedQuery) {
         queryEmbedding = await provider.embedQuery(query);
@@ -100,14 +73,12 @@ async function example4_asymmetricSearch() {
         [queryEmbedding] = await provider.embed([query]);
         console.log("✓ Used standard embedding");
     }
-    // Compute cosine similarity (simplified)
     const similarities = docEmbeddings.map((docEmb) => {
         const dotProduct = docEmb.reduce((sum, val, i) => sum + val * queryEmbedding[i], 0);
         const magnitude1 = Math.sqrt(docEmb.reduce((sum, val) => sum + val * val, 0));
         const magnitude2 = Math.sqrt(queryEmbedding.reduce((sum, val) => sum + val * val, 0));
         return dotProduct / (magnitude1 * magnitude2);
     });
-    // Show results
     console.log("\nSearch results:");
     similarities
         .map((sim, i) => ({ doc: documents[i], similarity: sim }))
@@ -117,47 +88,35 @@ async function example4_asymmetricSearch() {
     });
     console.log();
 }
-// ============================================================================
-// Example 5: Custom Priority Order
-// ============================================================================
 async function example5_customPriority() {
     console.log("Example 5: Custom priority order\n");
-    // Try local first, then cloud
     const customConfigs = [
-        { type: "ollama" }, // Free, local
-        { type: "openai", dimensions: 512 }, // Cheap, small dimensions
-        { type: "text-only" } // Ultimate fallback
+        { type: "ollama" },
+        { type: "openai", dimensions: 512 },
+        { type: "text-only" }
     ];
     const provider = await selectBestProvider(customConfigs);
     console.log(`Selected: ${provider.name}`);
     console.log(`Strategy: Try local → Try cheap cloud → Fallback\n`);
 }
-// ============================================================================
-// Example 6: Production Configuration
-// ============================================================================
 async function example6_production() {
     console.log("Example 6: Production-ready configuration\n");
-    // Production setup with redundancy
     const productionConfigs = [
-        // Primary: High-quality embeddings
         {
             type: "openai",
             model: "text-embedding-3-large",
             dimensions: 3072
         },
-        // Fallback 1: Smaller but still good
         {
             type: "openai",
             model: "text-embedding-3-small",
             dimensions: 1536
         },
-        // Fallback 2: Alternative provider
         {
             type: "voyage",
             model: "voyage-4-lite",
             dimensions: 1024
         },
-        // Fallback 3: Multi-provider gateway
         {
             type: "openrouter",
             model: "openai/text-embedding-3-small"
@@ -168,13 +127,9 @@ async function example6_production() {
     console.log(`  Dimensions: ${provider.dimensions}`);
     console.log(`  Type: ${provider.type}\n`);
 }
-// ============================================================================
-// Example 7: Batch Processing
-// ============================================================================
 async function example7_batchProcessing() {
     console.log("Example 7: Efficient batch processing\n");
     const provider = await selectBestProvider(getDefaultConfigs());
-    // Efficient: Single API call
     const startTime = Date.now();
     const texts = Array.from({ length: 100 }, (_, i) => `Document number ${i + 1} with some content`);
     const embeddings = await provider.embed(texts);
@@ -182,16 +137,12 @@ async function example7_batchProcessing() {
     console.log(`✓ Embedded ${embeddings.length} documents in ${duration}ms`);
     console.log(`  Average: ${(duration / embeddings.length).toFixed(2)}ms per document\n`);
 }
-// ============================================================================
-// Example 8: Error Handling
-// ============================================================================
 async function example8_errorHandling() {
     console.log("Example 8: Proper error handling\n");
     try {
-        // Invalid configuration
         const provider = createProvider({
             type: "openai",
-            dimensions: 999 // Invalid dimension!
+            dimensions: 999
         });
         await provider.embed(["test"]);
     }
@@ -200,9 +151,6 @@ async function example8_errorHandling() {
         console.log("✓ Errors are clear and actionable\n");
     }
 }
-// ============================================================================
-// Example 9: Health Monitoring
-// ============================================================================
 async function example9_healthMonitoring() {
     console.log("Example 9: Health monitoring\n");
     const providers = [
@@ -222,12 +170,8 @@ async function example9_healthMonitoring() {
         console.log();
     }
 }
-// ============================================================================
-// Example 10: Testing Setup
-// ============================================================================
 async function example10_testing() {
     console.log("Example 10: Testing setup\n");
-    // Use text-only provider for fast tests
     const testProvider = createProvider({ type: "text-only" });
     console.log("Test provider setup:");
     console.log(`  Name: ${testProvider.name}`);
@@ -237,9 +181,6 @@ async function example10_testing() {
     const embeddings = await testProvider.embed(["test1", "test2", "test3"]);
     console.log(`  Generated ${embeddings.length} mock embeddings\n`);
 }
-// ============================================================================
-// Run Examples
-// ============================================================================
 async function runExamples() {
     const examples = [
         example1_autoSelection,
@@ -263,7 +204,6 @@ async function runExamples() {
         console.log("─".repeat(80) + "\n");
     }
 }
-// Run if executed directly
 if (import.meta.url === `file://${process.argv[1]}`) {
     runExamples().catch(console.error);
 }

package/dist/memory/providers/factory.d.ts

@@ -1,48 +1,4 @@
-/**
- * Provider Factory with Graceful Degradation
- *
- * "Make the right things easy and the wrong things hard."
- *
- * This factory implements:
- * 1. Strategy Pattern - swappable providers
- * 2. Factory Pattern - centralized creation
- * 3. Graceful Degradation - automatic fallback to working providers
- */
 import type { IEmbeddingProvider, ProviderConfig } from "./types.js";
-/**
- * Create a provider from configuration
- *
- * @throws Error if provider type is invalid or required credentials are missing
- */
 export declare function createProvider(config: ProviderConfig): IEmbeddingProvider;
-/**
- * Select the best working provider from a list
- *
- * Implements graceful degradation:
- * - Tries each provider in order
- * - Returns first healthy provider
- * - Falls back to text-only if all fail
- *
- * @param configs - Array of provider configurations in priority order
- * @returns The first healthy provider or text-only fallback
- *
- * @example
- * ```typescript
- * const provider = await selectBestProvider([
- *   { type: "voyage", model: "voyage-code-3" },
- *   { type: "ollama" },
- *   { type: "openai" }
- * ]);
- * ```
- */
 export declare function selectBestProvider(configs: ProviderConfig[]): Promise<IEmbeddingProvider>;
-/**
- * Get default provider configurations
- *
- * Priority order:
- * 1. Voyage (code-specialized)
- * 2. Ollama (local, free)
- * 3. OpenAI (reliable)
- * 4. OpenRouter (fallback)
- */
 export declare function getDefaultConfigs(): ProviderConfig[];

package/dist/memory/providers/factory.js

@@ -1,23 +1,8 @@
-/**
- * Provider Factory with Graceful Degradation
- *
- * "Make the right things easy and the wrong things hard."
- *
- * This factory implements:
- * 1. Strategy Pattern - swappable providers
- * 2. Factory Pattern - centralized creation
- * 3. Graceful Degradation - automatic fallback to working providers
- */
 import { OllamaProvider } from "./ollama.js";
 import { OpenAIProvider } from "./openai.js";
 import { VoyageProvider } from "./voyage.js";
 import { OpenRouterProvider } from "./openrouter.js";
 import { TextOnlyProvider } from "./text-only.js";
-/**
- * Create a provider from configuration
- *
- * @throws Error if provider type is invalid or required credentials are missing
- */
 export function createProvider(config) {
     switch (config.type) {
         case "ollama":
@@ -34,29 +19,8 @@ export function createProvider(config) {
             throw new Error(`Unknown provider type: ${config.type}`);
     }
 }
-/**
- * Select the best working provider from a list
- *
- * Implements graceful degradation:
- * - Tries each provider in order
- * - Returns first healthy provider
- * - Falls back to text-only if all fail
- *
- * @param configs - Array of provider configurations in priority order
- * @returns The first healthy provider or text-only fallback
- *
- * @example
- * ```typescript
- * const provider = await selectBestProvider([
- *   { type: "voyage", model: "voyage-code-3" },
- *   { type: "ollama" },
- *   { type: "openai" }
- * ]);
- * ```
- */
 export async function selectBestProvider(configs) {
     const results = [];
-    // Try each provider
     for (const config of configs) {
         try {
             const provider = createProvider(config);
@@ -72,20 +36,10 @@ export async function selectBestProvider(configs) {
             console.warn(`✗ Failed to initialize ${config.type}:`, error instanceof Error ? error.message : error);
         }
     }
-    // Fallback to text-only
     console.warn("⚠️  All embedding providers failed. Falling back to text-only mode.");
     console.warn("   Semantic search will be limited to keyword matching.");
     return new TextOnlyProvider({ type: "text-only" });
 }
-/**
- * Get default provider configurations
- *
- * Priority order:
- * 1. Voyage (code-specialized)
- * 2. Ollama (local, free)
- * 3. OpenAI (reliable)
- * 4. OpenRouter (fallback)
- */
 export function getDefaultConfigs() {
     return [
         {

package/dist/memory/providers/index.d.ts

@@ -1,29 +1,3 @@
-/**
- * Embedding Providers Module
- *
- * Clean public API following the Dependency Inversion Principle.
- * Clients depend on abstractions (IEmbeddingProvider), not implementations.
- *
- * @example Basic usage
- * ```typescript
- * import { createProvider } from "./providers";
- *
- * const provider = createProvider({
- *   type: "voyage",
- *   model: "voyage-code-3"
- * });
- *
- * const embeddings = await provider.embed(["hello world"]);
- * ```
- *
- * @example Auto-selection with graceful degradation
- * ```typescript
- * import { selectBestProvider, getDefaultConfigs } from "./providers";
- *
- * const provider = await selectBestProvider(getDefaultConfigs());
- * // Will try providers in order and fallback to text-only if needed
- * ```
- */
 export type { Embedding, ProviderType, HealthCheckResult, ProviderConfig, IEmbeddingProvider } from "./types.js";
 export { OllamaProvider } from "./ollama.js";
 export { OpenAIProvider } from "./openai.js";

package/dist/memory/providers/index.js

@@ -1,34 +1,6 @@
-/**
- * Embedding Providers Module
- *
- * Clean public API following the Dependency Inversion Principle.
- * Clients depend on abstractions (IEmbeddingProvider), not implementations.
- *
- * @example Basic usage
- * ```typescript
- * import { createProvider } from "./providers";
- *
- * const provider = createProvider({
- *   type: "voyage",
- *   model: "voyage-code-3"
- * });
- *
- * const embeddings = await provider.embed(["hello world"]);
- * ```
- *
- * @example Auto-selection with graceful degradation
- * ```typescript
- * import { selectBestProvider, getDefaultConfigs } from "./providers";
- *
- * const provider = await selectBestProvider(getDefaultConfigs());
- * // Will try providers in order and fallback to text-only if needed
- * ```
- */
-// Concrete implementations (export for advanced use cases)
 export { OllamaProvider } from "./ollama.js";
 export { OpenAIProvider } from "./openai.js";
 export { VoyageProvider } from "./voyage.js";
 export { OpenRouterProvider } from "./openrouter.js";
 export { TextOnlyProvider } from "./text-only.js";
-// Factory functions (recommended API)
 export { createProvider, selectBestProvider, getDefaultConfigs } from "./factory.js";

package/dist/memory/providers/ollama.d.ts

@@ -1,9 +1,3 @@
-/**
- * Ollama Embedding Provider
- *
- * Local-first embedding using Ollama's API.
- * Prioritizes privacy and zero-cost operation.
- */
 import type { Embedding, HealthCheckResult, IEmbeddingProvider, ProviderConfig } from "./types.js";
 export declare class OllamaProvider implements IEmbeddingProvider {
     readonly name = "Ollama";

package/dist/memory/providers/ollama.js

@@ -1,9 +1,3 @@
-/**
- * Ollama Embedding Provider
- *
- * Local-first embedding using Ollama's API.
- * Prioritizes privacy and zero-cost operation.
- */
 export class OllamaProvider {
     name = "Ollama";
     type = "ollama";
@@ -13,7 +7,7 @@ export class OllamaProvider {
     constructor(config) {
         this.baseUrl = config.baseUrl || "http://localhost:11434";
         this.model = config.model || "nomic-embed-text";
-        this.dimensions = config.dimensions || 768; // nomic-embed-text default
+        this.dimensions = config.dimensions || 768;
     }
     async healthCheck() {
         try {
@@ -46,7 +40,6 @@ export class OllamaProvider {
     }
     async embed(texts) {
         const embeddings = [];
-        // Ollama API processes one text at a time
         for (const text of texts) {
             const response = await fetch(`${this.baseUrl}/api/embeddings`, {
                 method: "POST",

package/dist/memory/providers/openai.d.ts

@@ -1,9 +1,3 @@
-/**
- * OpenAI Embedding Provider
- *
- * Industry-standard embeddings with flexible dimensionality.
- * Supports text-embedding-3-small and text-embedding-3-large models.
- */
 import type { Embedding, HealthCheckResult, IEmbeddingProvider, ProviderConfig } from "./types.js";
 export declare class OpenAIProvider implements IEmbeddingProvider {
     readonly name = "OpenAI";

package/dist/memory/providers/openai.js

@@ -1,9 +1,3 @@
-/**
- * OpenAI Embedding Provider
- *
- * Industry-standard embeddings with flexible dimensionality.
- * Supports text-embedding-3-small and text-embedding-3-large models.
- */
 const VALID_DIMENSIONS = [256, 512, 1536, 3072];
 export class OpenAIProvider {
     name = "OpenAI";
@@ -25,7 +19,7 @@ export class OpenAIProvider {
     }
     validateDimensions(dim) {
         if (!dim)
-            return 1536; // Default for text-embedding-3-small
+            return 1536;
         if (!VALID_DIMENSIONS.includes(dim)) {
             throw new Error(`Invalid dimensions ${dim}. Must be one of: ${VALID_DIMENSIONS.join(", ")}`);
         }
@@ -33,7 +27,6 @@ export class OpenAIProvider {
     }
     async healthCheck() {
         try {
-            // Lightweight check: list models endpoint
             const response = await fetch(`${this.baseUrl}/models`, {
                 headers: {
                     "Authorization": `Bearer ${this.apiKey}`,

package/dist/memory/providers/openrouter.d.ts

@@ -1,9 +1,3 @@
-/**
- * OpenRouter Embedding Provider
- *
- * Multi-model gateway supporting various embedding providers.
- * Requires HTTP-Referer and X-Title headers for API tracking.
- */
 import type { Embedding, HealthCheckResult, IEmbeddingProvider, ProviderConfig } from "./types.js";
 export declare class OpenRouterProvider implements IEmbeddingProvider {
     readonly name = "OpenRouter";

package/dist/memory/providers/openrouter.js

@@ -1,9 +1,3 @@
-/**
- * OpenRouter Embedding Provider
- *
- * Multi-model gateway supporting various embedding providers.
- * Requires HTTP-Referer and X-Title headers for API tracking.
- */
 export class OpenRouterProvider {
     name = "OpenRouter";
     type = "openrouter";
@@ -22,13 +16,11 @@ export class OpenRouterProvider {
         this.model = config.model || "openai/text-embedding-3-small";
         this.baseUrl = config.baseUrl || "https://openrouter.ai/api/v1";
         this.dimensions = config.dimensions || 1536;
-        // OpenRouter requires these headers for tracking
         this.referer = process.env.OPENROUTER_REFERER || "https://maskweaver.dev";
         this.title = process.env.OPENROUTER_TITLE || "MaskWeaver";
     }
     async healthCheck() {
         try {
-            // Check API key validity
             const response = await fetch(`${this.baseUrl}/auth/key`, {
                 headers: {
                     "Authorization": `Bearer ${this.apiKey}`,

package/dist/memory/providers/text-only.d.ts

@@ -1,21 +1,8 @@
-/**
- * Text-Only Provider (Null Object Pattern)
- *
- * Graceful degradation when no embedding service is available.
- * Returns empty vectors, allowing the system to function in text-only mode.
- * Vector search is skipped; only FTS keyword matching is used.
- *
- * Use case: Development, testing, or when embedding APIs are unavailable.
- */
 import type { Embedding, HealthCheckResult, IEmbeddingProvider, ProviderConfig } from "./types.js";
 export declare class TextOnlyProvider implements IEmbeddingProvider {
     readonly name = "Text-Only (No Embeddings)";
     readonly type: "text-only";
     readonly dimensions: number;
-    /**
-     * When true, signals that this provider cannot produce meaningful embeddings.
-     * Consumers should skip vector search and rely on text/keyword search only.
-     */
     readonly isTextOnly = true;
     constructor(config: ProviderConfig);
     healthCheck(): Promise<HealthCheckResult>;

package/dist/memory/providers/text-only.js

@@ -1,35 +1,18 @@
-/**
- * Text-Only Provider (Null Object Pattern)
- *
- * Graceful degradation when no embedding service is available.
- * Returns empty vectors, allowing the system to function in text-only mode.
- * Vector search is skipped; only FTS keyword matching is used.
- *
- * Use case: Development, testing, or when embedding APIs are unavailable.
- */
 export class TextOnlyProvider {
     name = "Text-Only (No Embeddings)";
     type = "text-only";
     dimensions;
-    /**
-     * When true, signals that this provider cannot produce meaningful embeddings.
-     * Consumers should skip vector search and rely on text/keyword search only.
-     */
     isTextOnly = true;
     constructor(config) {
-        // dimensions = 0 signals "no real embeddings" — consumers should skip vector ops.
-        // If an explicit dimension is provided (e.g., for testing), honor it.
         this.dimensions = config.dimensions ?? 0;
     }
     async healthCheck() {
-        // Always healthy - it's a fallback
         return {
             ok: true,
             hint: "Text-only mode: semantic search will be limited to keyword matching"
         };
     }
     async embed(texts) {
-        // Return empty vectors — dimension 0 signals "no real embedding"
         return texts.map(() => []);
     }
     async embedQuery(text) {

package/dist/memory/providers/types.d.ts

@@ -1,23 +1,10 @@
-/**
- * Embedding Provider Types
- *
- * Clean interface design following Interface Segregation Principle.
- * Each provider implements the IEmbeddingProvider contract while maintaining
- * flexibility for provider-specific optimizations.
- */
 export type Embedding = number[];
 export type ProviderType = "ollama" | "openai" | "voyage" | "openrouter" | "text-only";
-/**
- * Health check result with actionable feedback
- */
 export interface HealthCheckResult {
     ok: boolean;
     reason?: string;
     hint?: string;
 }
-/**
- * Provider configuration - immutable after construction
- */
 export interface ProviderConfig {
     type: ProviderType;
     apiKey?: string;
@@ -25,38 +12,12 @@ export interface ProviderConfig {
     baseUrl?: string;
     dimensions?: number;
 }
-/**
- * Core embedding provider interface
- *
- * Design principle: "Program to an interface, not an implementation"
- * This enables Strategy Pattern for swappable embedding backends.
- */
 export interface IEmbeddingProvider {
-    /** Provider identifier */
     readonly name: string;
-    /** Provider type for factory selection */
     readonly type: ProviderType;
-    /** Output vector dimensions */
     readonly dimensions: number;
-    /**
-     * Verify provider is ready and reachable
-     * Should be fast and non-destructive
-     */
     healthCheck(): Promise<HealthCheckResult>;
-    /**
-     * Generate embeddings for multiple texts
-     * @param texts - Array of text strings to embed
-     * @returns Array of embedding vectors
-     */
     embed(texts: string[]): Promise<Embedding[]>;
-    /**
-     * Optional: Generate code-optimized embeddings
-     * Some providers (like Voyage) have specialized code models
-     */
     embedCode?(texts: string[]): Promise<Embedding[]>;
-    /**
-     * Optional: Generate query-optimized embedding
-     * For asymmetric search (query vs document)
-     */
     embedQuery?(text: string): Promise<Embedding>;
 }

package/dist/memory/providers/types.js

@@ -1,8 +1 @@
-/**
- * Embedding Provider Types
- *
- * Clean interface design following Interface Segregation Principle.
- * Each provider implements the IEmbeddingProvider contract while maintaining
- * flexibility for provider-specific optimizations.
- */
 export {};