maskweaver 0.9.4 → 0.9.6

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 {};

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

@@ -1,11 +1,3 @@
-/**
- * Voyage AI Embedding Provider
- *
- * Specialized embeddings with code-specific models (voyage-code-3).
- * Supports asymmetric search with input_type distinction.
- *
- * Key feature: embedCode() method for superior code understanding.
- */
 import type { Embedding, HealthCheckResult, IEmbeddingProvider, ProviderConfig } from "./types.js";
 export declare class VoyageProvider implements IEmbeddingProvider {
     readonly name = "Voyage AI";
@@ -17,22 +9,8 @@ export declare class VoyageProvider implements IEmbeddingProvider {
     constructor(config: ProviderConfig);
     private validateDimensions;
     healthCheck(): Promise<HealthCheckResult>;
-    /**
-     * General-purpose embedding (documents)
-     */
     embed(texts: string[]): Promise<Embedding[]>;
-    /**
-     * Code-optimized embedding
-     * Use voyage-code-3 model for best results
-     */
     embedCode(texts: string[]): Promise<Embedding[]>;
-    /**
-     * Query-optimized embedding
-     * For asymmetric search (query vs document)
-     */
     embedQuery(text: string): Promise<Embedding>;
-    /**
-     * Core embedding method with input_type specification
-     */
     private embedWithType;
 }

package/dist/memory/providers/voyage.js

@@ -1,11 +1,3 @@
-/**
- * Voyage AI Embedding Provider
- *
- * Specialized embeddings with code-specific models (voyage-code-3).
- * Supports asymmetric search with input_type distinction.
- *
- * Key feature: embedCode() method for superior code understanding.
- */
 const VALID_DIMENSIONS = [256, 512, 1024, 2048];
 const CODE_MODELS = ["voyage-code-3"];
 const GENERAL_MODELS = ["voyage-4-lite", "voyage-4-large"];
@@ -28,7 +20,7 @@ export class VoyageProvider {
     }
     validateDimensions(dim) {
         if (!dim)
-            return 1024; // Default for voyage-4-lite
+            return 1024;
         if (!VALID_DIMENSIONS.includes(dim)) {
             throw new Error(`Invalid dimensions ${dim}. Must be one of: ${VALID_DIMENSIONS.join(", ")}`);
         }
@@ -36,7 +28,6 @@ export class VoyageProvider {
     }
     async healthCheck() {
         try {
-            // Test with a minimal embedding request
             const response = await fetch(`${this.baseUrl}/embeddings`, {
                 method: "POST",
                 headers: {
@@ -74,16 +65,9 @@ export class VoyageProvider {
             };
         }
     }
-    /**
-     * General-purpose embedding (documents)
-     */
     async embed(texts) {
         return this.embedWithType(texts, "document");
     }
-    /**
-     * Code-optimized embedding
-     * Use voyage-code-3 model for best results
-     */
     async embedCode(texts) {
         const isCodeModel = CODE_MODELS.includes(this.model);
         if (!isCodeModel) {
@@ -91,17 +75,10 @@ export class VoyageProvider {
         }
         return this.embedWithType(texts, "document");
     }
-    /**
-     * Query-optimized embedding
-     * For asymmetric search (query vs document)
-     */
     async embedQuery(text) {
         const [embedding] = await this.embedWithType([text], "query");
         return embedding;
     }
-    /**
-     * Core embedding method with input_type specification
-     */
     async embedWithType(texts, inputType) {
         const response = await fetch(`${this.baseUrl}/embeddings`, {
             method: "POST",

package/dist/memory/search/hybrid.d.ts

@@ -1,15 +1,3 @@
-/**
- * Hybrid Search - Combine vector and text search
- *
- * Simple weighted combination of vector similarity and FTS scores.
- * Gracefully degrades to text-only when no embedding is available.
- */
 import type { SearchResult } from '../core.js';
 import type { SearchOptions } from '../store/sqlite.js';
-/**
- * Hybrid search combining vector and text search.
- *
- * If queryEmbedding is empty/missing, automatically falls back
- * to text-only search with adjusted scoring.
- */
 export declare function hybridSearch(query: string, queryEmbedding: number[], options?: SearchOptions): SearchResult[];

package/dist/memory/search/hybrid.js

@@ -1,42 +1,23 @@
-/**
- * Hybrid Search - Combine vector and text search
- *
- * Simple weighted combination of vector similarity and FTS scores.
- * Gracefully degrades to text-only when no embedding is available.
- */
 import { getDatabase } from '../store/sqlite.js';
 const DEFAULT_VECTOR_WEIGHT = 0.7;
 const DEFAULT_TEXT_WEIGHT = 0.3;
 const DEFAULT_MIN_SCORE = 0.35;
 const DEFAULT_MAX_RESULTS = 6;
-/**
- * Hybrid search combining vector and text search.
- *
- * If queryEmbedding is empty/missing, automatically falls back
- * to text-only search with adjusted scoring.
- */
 export function hybridSearch(query, queryEmbedding, options = {}) {
     const { limit = DEFAULT_MAX_RESULTS, minScore = DEFAULT_MIN_SCORE, vectorWeight = DEFAULT_VECTOR_WEIGHT, textWeight = DEFAULT_TEXT_WEIGHT, sourceFilter, } = options;
     const db = getDatabase();
-    // SQLite not available - return empty results (graceful degradation)
     if (!db) {
         return [];
     }
-    // Get more candidates for reranking
     const candidateLimit = limit * 3;
-    // Determine if we can do vector search
     const hasEmbedding = queryEmbedding && queryEmbedding.length > 0;
-    // Run vector search only if we have a real embedding
     const vectorResults = hasEmbedding
         ? db.searchByVector(queryEmbedding, candidateLimit, sourceFilter)
         : [];
-    // Always try text search
     const textResults = db.searchByText(query, candidateLimit);
-    // If both are empty, nothing to merge
     if (vectorResults.length === 0 && textResults.length === 0) {
         return [];
     }
-    // Merge results
     const scoreMap = new Map();
     for (const result of vectorResults) {
         scoreMap.set(result.chunk.id, {
@@ -58,14 +39,12 @@ export function hybridSearch(query, queryEmbedding, options = {}) {
             });
         }
     }
-    // Calculate combined scores
-    // When in text-only mode, use text score directly (don't penalize via vectorWeight)
     const effectiveMinScore = hasEmbedding ? minScore : minScore * textWeight;
     const results = Array.from(scoreMap.values())
         .map(({ chunk, vectorScore, textScore }) => {
         const combinedScore = hasEmbedding
             ? vectorScore * vectorWeight + textScore * textWeight
-            : textScore; // Pure text mode — use raw text score
+            : textScore;
         return {
             chunk,
             score: combinedScore,

package/dist/memory/store/sqlite.d.ts

@@ -1,21 +1,5 @@
-/**
- * SQLite Storage - Persistent chunk and embedding storage
- *
- * Uses better-sqlite3 for Node.js compatibility.
- * WAL mode for concurrent access.
- *
- * NOTE: better-sqlite3 is an optional dependency.
- * This module uses dynamic import to avoid errors when not installed.
- */
 import { type Chunk, type SearchResult } from '../core.js';
-/**
- * Check if SQLite is available without throwing.
- * Returns true if SQLite can be loaded, false otherwise.
- */
 export declare function isSqliteAvailable(): boolean;
-/**
- * Get the reason SQLite is unavailable.
- */
 export declare function getSqliteUnavailableReason(): string;
 export interface SearchOptions {
     limit?: number;
@@ -29,62 +13,19 @@ export declare class MemoryDatabase {
     private statements;
     private ftsAvailable;
     private constructor();
-    /**
-     * Create a new MemoryDatabase instance.
-     * Uses async factory pattern because better-sqlite3 is dynamically imported.
-     * Returns null if SQLite is not available (graceful degradation).
-     */
     static create(dbPath: string): Promise<MemoryDatabase | null>;
-    /**
-     * Initialize database schema.
-     */
     private initSchema;
-    /**
-     * Prepare SQL statements for reuse.
-     */
     private prepareStatements;
-    /**
-     * Insert or update chunk.
-     *
-     * If embedding is empty (e.g., text-only mode), the chunk is stored
-     * but the embedding row is skipped. This allows text search to work
-     * while vector search gracefully returns no results for these chunks.
-     */
     upsertChunk(chunk: Chunk, embedding: number[]): number;
-    /**
-     * Bulk insert chunks in transaction.
-     */
     upsertChunks(chunks: Array<{
         chunk: Chunk;
         embedding: number[];
     }>): number[];
-    /**
-     * Delete chunks by path.
-     */
     deleteChunksByPath(path: string): number;
-    /**
-     * Check if chunk changed.
-     */
     isChunkChanged(path: string, hash: string): boolean;
-    /**
-     * Get chunks by path.
-     */
     getChunksByPath(path: string): Chunk[];
-    /**
-     * Vector similarity search.
-     *
-     * Returns empty results if queryEmbedding is empty (e.g., text-only mode).
-     * Skips stored embeddings with dimension mismatches instead of crashing.
-     */
     searchByVector(queryEmbedding: number[], limit?: number, sourceFilter?: Chunk['source'][]): SearchResult[];
-    /**
-     * Full-text search using FTS5.
-     * Returns empty results if FTS is not available.
-     */
     searchByText(query: string, limit?: number): SearchResult[];
-    /**
-     * Normalize FTS query.
-     */
     private normalizeFtsQuery;
     recordMaskUsage(maskName: string, taskDescription?: string, effectivenessScore?: number): void;
     getMaskStats(): Array<{
@@ -103,21 +44,8 @@ export declare class MemoryDatabase {
     optimize(): void;
     close(): void;
 }
-/**
- * Initialize the database.
- * Returns null if SQLite is not available (graceful degradation).
- */
 export declare function initDatabase(dbPath: string): Promise<MemoryDatabase | null>;
-/**
- * Get the database instance.
- * Returns null if SQLite is not available or not initialized.
- * Use this for optional memory features.
- */
 export declare function getDatabase(): MemoryDatabase | null;
-/**
- * Try to get the database instance, returning null if not initialized.
- * Use this when database access is optional (e.g., in intake stage).
- */
 export declare function tryGetDatabase(): MemoryDatabase | null;
 export declare function upsertChunk(chunk: Chunk, embedding: number[]): number;
 export declare function searchByVector(embedding: number[], limit?: number): SearchResult[];