@skillsmith/core 0.1.0

package/dist/src/embeddings/index.js

@@ -0,0 +1,397 @@
+/**
+ * SMI-584: Semantic Embeddings Service
+ * SMI-754: Added fallback mode for deterministic mock embeddings
+ * SMI-1127: Lazy loading of @xenova/transformers to avoid CLI crashes from sharp
+ *
+ * Uses all-MiniLM-L6-v2 model for fast, accurate skill embeddings.
+ * Supports fallback mode for tests and when model unavailable.
+ *
+ * @see ADR-009: Embedding Service Fallback Strategy
+ */
+import Database from 'better-sqlite3';
+// Lazy-loaded pipeline function - only loaded when embeddings are actually used
+let pipelineModule = null;
+let pipelineLoadPromise = null;
+let pipelineLoadFailed = false;
+let pipelineLoadError = null;
+/**
+ * Lazily load the @xenova/transformers module.
+ * This avoids loading sharp at startup, which causes CLI crashes.
+ */
+async function loadTransformersModule() {
+    // Return cached module if already loaded
+    if (pipelineModule) {
+        return pipelineModule;
+    }
+    // Return null if we already tried and failed
+    if (pipelineLoadFailed) {
+        return null;
+    }
+    // Start loading if not already in progress
+    if (!pipelineLoadPromise) {
+        pipelineLoadPromise = import('@xenova/transformers')
+            .then((mod) => {
+            pipelineModule = mod;
+            return mod;
+        })
+            .catch((err) => {
+            pipelineLoadFailed = true;
+            pipelineLoadError = err instanceof Error ? err : new Error(String(err));
+            return null;
+        });
+    }
+    const result = await pipelineLoadPromise;
+    return result || null;
+}
+/**
+ * Check if fallback mode should be used based on environment
+ */
+function shouldUseFallback(explicit) {
+    if (explicit !== undefined) {
+        return explicit;
+    }
+    // Check environment variable
+    const envValue = process.env.SKILLSMITH_USE_MOCK_EMBEDDINGS;
+    if (envValue !== undefined) {
+        return envValue === 'true' || envValue === '1';
+    }
+    // Default to real embeddings
+    return false;
+}
+/**
+ * Generate a deterministic hash from text for mock embeddings.
+ * Uses a simple but effective string hashing algorithm.
+ */
+function hashText(text) {
+    let hash = 0;
+    for (let i = 0; i < text.length; i++) {
+        const char = text.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash = hash & hash; // Convert to 32-bit integer
+    }
+    return hash;
+}
+/**
+ * Generate deterministic mock embedding based on text content.
+ * Produces consistent vectors for the same input text.
+ */
+function generateMockEmbedding(text, dimension) {
+    const embedding = new Float32Array(dimension);
+    const baseHash = hashText(text);
+    for (let i = 0; i < dimension; i++) {
+        // Use sine wave with hash-based offset for pseudo-random but deterministic values
+        const value = Math.sin(baseHash + i * 0.1) * 0.5 + 0.5;
+        embedding[i] = value;
+    }
+    // Normalize the vector
+    let norm = 0;
+    for (let i = 0; i < dimension; i++) {
+        norm += embedding[i] * embedding[i];
+    }
+    norm = Math.sqrt(norm);
+    if (norm > 0) {
+        for (let i = 0; i < dimension; i++) {
+            embedding[i] /= norm;
+        }
+    }
+    return embedding;
+}
+export class EmbeddingService {
+    model = null;
+    modelPromise = null;
+    modelLoadFailed = false;
+    db = null;
+    modelName = 'Xenova/all-MiniLM-L6-v2';
+    embeddingDim = 384;
+    useFallback;
+    /**
+     * Create an EmbeddingService instance.
+     *
+     * @param optionsOrDbPath - Options object or legacy dbPath string
+     *
+     * @example
+     * // Real embeddings (default)
+     * const service = new EmbeddingService({ dbPath: './cache.db' });
+     *
+     * @example
+     * // Forced fallback mode for tests
+     * const service = new EmbeddingService({ useFallback: true });
+     *
+     * @example
+     * // Environment-controlled (set SKILLSMITH_USE_MOCK_EMBEDDINGS=true)
+     * const service = new EmbeddingService();
+     */
+    constructor(optionsOrDbPath) {
+        // Support legacy string argument for backward compatibility
+        const options = typeof optionsOrDbPath === 'string' ? { dbPath: optionsOrDbPath } : (optionsOrDbPath ?? {});
+        this.useFallback = shouldUseFallback(options.useFallback);
+        if (options.dbPath) {
+            this.db = new Database(options.dbPath);
+            this.initEmbeddingTable();
+        }
+    }
+    /**
+     * Check if service is running in fallback (mock) mode
+     */
+    isUsingFallback() {
+        return this.useFallback || this.modelLoadFailed;
+    }
+    initEmbeddingTable() {
+        if (!this.db)
+            return;
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS skill_embeddings (
+        skill_id TEXT PRIMARY KEY,
+        embedding BLOB NOT NULL,
+        text TEXT NOT NULL,
+        created_at INTEGER DEFAULT (unixepoch())
+      )
+    `);
+        this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_embeddings_skill 
+      ON skill_embeddings(skill_id)
+    `);
+    }
+    /**
+     * Check if the transformers module is available without loading it.
+     * This is a synchronous check that returns the current known state.
+     *
+     * @returns true if module is loaded, false if loading failed, undefined if not yet attempted
+     */
+    static isTransformersAvailable() {
+        if (pipelineModule)
+            return true;
+        if (pipelineLoadFailed)
+            return false;
+        return undefined;
+    }
+    /**
+     * Check if embeddings functionality is available.
+     * Attempts to load the transformers module if not yet loaded.
+     *
+     * @returns true if embeddings can be used, false otherwise
+     */
+    static async checkAvailability() {
+        const mod = await loadTransformersModule();
+        return mod !== null;
+    }
+    /**
+     * Get the error that occurred when loading the transformers module, if any.
+     */
+    static getTransformersLoadError() {
+        return pipelineLoadError;
+    }
+    /**
+     * Lazily load the embedding model.
+     * Returns null if in fallback mode or if model loading fails.
+     */
+    async loadModel() {
+        // Skip loading if in fallback mode
+        if (this.useFallback) {
+            return null;
+        }
+        // Return cached model if available
+        if (this.model)
+            return this.model;
+        // Return null if we already tried and failed
+        if (this.modelLoadFailed) {
+            return null;
+        }
+        if (!this.modelPromise) {
+            // Lazily load the transformers module first
+            this.modelPromise = (async () => {
+                const transformers = await loadTransformersModule();
+                if (!transformers) {
+                    throw new Error(pipelineLoadError?.message ||
+                        'Failed to load @xenova/transformers module (sharp may not be available)');
+                }
+                return transformers.pipeline('feature-extraction', this.modelName, {
+                    quantized: true, // Use quantized model for faster inference
+                });
+            })();
+        }
+        try {
+            this.model = await this.modelPromise;
+            return this.model;
+        }
+        catch (error) {
+            // Model loading failed - switch to fallback mode
+            this.modelLoadFailed = true;
+            console.warn(`[EmbeddingService] Failed to load model "${this.modelName}", using fallback mode:`, error instanceof Error ? error.message : error);
+            return null;
+        }
+    }
+    /**
+     * Generate embedding for a single text.
+     * Uses real ONNX model when available, falls back to deterministic mock otherwise.
+     */
+    async embed(text) {
+        // Truncate text if too long (model max is 256 tokens)
+        const truncated = text.slice(0, 1000);
+        // Use fallback if configured or model unavailable
+        if (this.useFallback || this.modelLoadFailed) {
+            return generateMockEmbedding(truncated, this.embeddingDim);
+        }
+        // Try to load and use real model
+        const model = await this.loadModel();
+        if (!model) {
+            // Model loading failed, use fallback
+            return generateMockEmbedding(truncated, this.embeddingDim);
+        }
+        const output = await model(truncated, {
+            pooling: 'mean',
+            normalize: true,
+        });
+        // Extract embedding data
+        const embedding = new Float32Array(this.embeddingDim);
+        for (let i = 0; i < this.embeddingDim; i++) {
+            embedding[i] = output.data[i];
+        }
+        return embedding;
+    }
+    /**
+     * Batch embed multiple texts efficiently.
+     * In fallback mode, processes synchronously for speed.
+     */
+    async embedBatch(texts) {
+        const results = [];
+        // In fallback mode, process synchronously (much faster)
+        if (this.useFallback || this.modelLoadFailed) {
+            for (const { id, text } of texts) {
+                const truncated = text.slice(0, 1000);
+                const embedding = generateMockEmbedding(truncated, this.embeddingDim);
+                results.push({ skillId: id, embedding, text });
+            }
+            return results;
+        }
+        // Try to load model for real embeddings
+        await this.loadModel();
+        // Process in batches of 32 for efficiency
+        const batchSize = 32;
+        for (let i = 0; i < texts.length; i += batchSize) {
+            const batch = texts.slice(i, i + batchSize);
+            for (const { id, text } of batch) {
+                const embedding = await this.embed(text);
+                results.push({
+                    skillId: id,
+                    embedding,
+                    text,
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * Store embedding in SQLite cache
+     */
+    storeEmbedding(skillId, embedding, text) {
+        if (!this.db)
+            return;
+        const buffer = Buffer.from(embedding.buffer);
+        const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO skill_embeddings (skill_id, embedding, text, created_at)
+      VALUES (?, ?, ?, unixepoch())
+    `);
+        stmt.run(skillId, buffer, text);
+    }
+    /**
+     * Retrieve cached embedding
+     */
+    getEmbedding(skillId) {
+        if (!this.db)
+            return null;
+        const stmt = this.db.prepare(`
+      SELECT embedding FROM skill_embeddings WHERE skill_id = ?
+    `);
+        const row = stmt.get(skillId);
+        if (!row)
+            return null;
+        return new Float32Array(row.embedding.buffer.slice(row.embedding.byteOffset, row.embedding.byteOffset + row.embedding.byteLength));
+    }
+    /**
+     * Get all cached embeddings
+     */
+    getAllEmbeddings() {
+        if (!this.db)
+            return new Map();
+        const stmt = this.db.prepare(`
+      SELECT skill_id, embedding FROM skill_embeddings
+    `);
+        const rows = stmt.all();
+        const result = new Map();
+        for (const row of rows) {
+            const embedding = new Float32Array(row.embedding.buffer.slice(row.embedding.byteOffset, row.embedding.byteOffset + row.embedding.byteLength));
+            result.set(row.skill_id, embedding);
+        }
+        return result;
+    }
+    /**
+     * Compute cosine similarity between two embeddings
+     */
+    cosineSimilarity(a, b) {
+        if (a.length !== b.length) {
+            throw new Error('Embeddings must have same dimension');
+        }
+        let dotProduct = 0;
+        let normA = 0;
+        let normB = 0;
+        for (let i = 0; i < a.length; i++) {
+            dotProduct += a[i] * b[i];
+            normA += a[i] * a[i];
+            normB += b[i] * b[i];
+        }
+        if (normA === 0 || normB === 0)
+            return 0;
+        return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+    }
+    /**
+     * Find most similar skills to a query embedding
+     */
+    findSimilar(queryEmbedding, topK = 10) {
+        const allEmbeddings = this.getAllEmbeddings();
+        const results = [];
+        for (const [skillId, embedding] of allEmbeddings) {
+            const score = this.cosineSimilarity(queryEmbedding, embedding);
+            results.push({ skillId, score });
+        }
+        // Sort by similarity score descending
+        results.sort((a, b) => b.score - a.score);
+        return results.slice(0, topK);
+    }
+    /**
+     * Pre-compute embeddings for all skills in database
+     */
+    async precomputeEmbeddings(skills) {
+        let count = 0;
+        for (const skill of skills) {
+            // Check if already cached
+            const existing = this.getEmbedding(skill.id);
+            if (existing)
+                continue;
+            // Create text representation for embedding
+            const text = `${skill.name} ${skill.description}`;
+            const embedding = await this.embed(text);
+            this.storeEmbedding(skill.id, embedding, text);
+            count++;
+        }
+        return count;
+    }
+    /**
+     * Close database connection
+     */
+    close() {
+        if (this.db) {
+            this.db.close();
+            this.db = null;
+        }
+    }
+}
+// Export testing utilities for use in test files
+export const testUtils = {
+    /** Generate a deterministic mock embedding (for testing) */
+    generateMockEmbedding,
+    /** Generate a hash from text (for testing) */
+    hashText,
+};
+export default EmbeddingService;
+//# sourceMappingURL=index.js.map

package/dist/src/embeddings/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/embeddings/index.ts"],"names":[],"mappings":"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"}

package/dist/src/errors/SkillsmithError.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Skillsmith Error Classes - SMI-881
+ *
+ * Custom error classes with proper cause chaining for better error propagation.
+ * Ensures stack traces and context are preserved through error handling layers.
+ */
+/**
+ * Base error class for all Skillsmith errors.
+ * Preserves cause chain and provides structured error information.
+ */
+export declare class SkillsmithError extends Error {
+    /** Error code for programmatic handling */
+    readonly code: string;
+    /** Additional context about the error */
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, options?: {
+        code?: string;
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+    /**
+     * Get the full error chain as an array
+     */
+    getErrorChain(): Error[];
+    /**
+     * Format error with full context for logging
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Network-related errors (fetch failures, timeouts, etc.)
+ */
+export declare class NetworkError extends SkillsmithError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+        url?: string;
+        statusCode?: number;
+        context?: Record<string, unknown>;
+    });
+}
+/**
+ * API-specific errors (rate limits, auth failures, etc.)
+ *
+ * Note: Rate limit detection includes both 429 (standard) and 403 (GitHub).
+ * GitHub returns 403 Forbidden for rate limit exceeded instead of 429.
+ * See: https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api
+ */
+export declare class ApiError extends SkillsmithError {
+    /** HTTP status code if applicable */
+    readonly statusCode?: number;
+    constructor(message: string, options?: {
+        cause?: unknown;
+        statusCode?: number;
+        url?: string;
+        context?: Record<string, unknown>;
+    });
+    /**
+     * Check if this is a rate limit error
+     */
+    isRateLimitError(): boolean;
+    /**
+     * Check if this is a not found error
+     */
+    isNotFoundError(): boolean;
+    /**
+     * Check if this is a server error (5xx)
+     */
+    isServerError(): boolean;
+}
+/**
+ * Validation errors (invalid input, schema violations)
+ */
+export declare class ValidationError extends SkillsmithError {
+    /** Field that failed validation */
+    readonly field?: string;
+    constructor(message: string, options?: {
+        cause?: unknown;
+        field?: string;
+        context?: Record<string, unknown>;
+    });
+}
+/**
+ * Skill-related errors (not found, invalid structure, etc.)
+ */
+export declare class SkillError extends SkillsmithError {
+    /** Skill ID if applicable */
+    readonly skillId?: string;
+    constructor(message: string, options?: {
+        cause?: unknown;
+        skillId?: string;
+        context?: Record<string, unknown>;
+    });
+}
+/**
+ * Configuration errors
+ */
+export declare class ConfigurationError extends SkillsmithError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+/**
+ * Wrap an unknown error in a SkillsmithError if not already one
+ */
+export declare function wrapError(error: unknown, message: string, options?: {
+    code?: string;
+    context?: Record<string, unknown>;
+}): SkillsmithError;
+/**
+ * Extract error message from unknown error
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Check if error is a specific type
+ */
+export declare function isSkillsmithError(error: unknown): error is SkillsmithError;
+//# sourceMappingURL=SkillsmithError.d.ts.map

package/dist/src/errors/SkillsmithError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SkillsmithError.d.ts","sourceRoot":"","sources":["../../../src/errors/SkillsmithError.ts"],"names":[],"mappings":"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"}