@skillsmith/core 0.1.0

package/dist/src/learning/types.js

@@ -0,0 +1,112 @@
+/**
+ * @fileoverview Type definitions for Recommendation Learning Loop
+ * @module @skillsmith/core/learning/types
+ * @see docs/phase4/epic1/recommendation-learning-loop-design.md
+ *
+ * Epic 1 - Sub-issue 5: Build Recommendation Learning Loop
+ * Owner: Data Scientist
+ *
+ * Provides type-safe interfaces for:
+ * - Signal collection (accept/dismiss/usage)
+ * - User preference profiles
+ * - Learning algorithm configuration
+ * - Privacy-preserving storage
+ */
+/**
+ * User interaction signal types for recommendation learning
+ */
+export var SignalType;
+(function (SignalType) {
+    /** User accepted and installed recommended skill */
+    SignalType["ACCEPT"] = "accept";
+    /** User explicitly dismissed recommendation */
+    SignalType["DISMISS"] = "dismiss";
+    /** User actively uses installed skill (daily usage) */
+    SignalType["USAGE_DAILY"] = "usage_daily";
+    /** User rarely uses installed skill (weekly usage) */
+    SignalType["USAGE_WEEKLY"] = "usage_weekly";
+    /** Skill installed but never used (30+ days) */
+    SignalType["ABANDONED"] = "abandoned";
+    /** User uninstalled previously accepted skill */
+    SignalType["UNINSTALL"] = "uninstall";
+})(SignalType || (SignalType = {}));
+/**
+ * Signal strength weights for learning algorithm
+ * Range: [-1.0, 1.0] where:
+ * - Positive = user preference signal
+ * - Negative = user rejection signal
+ */
+export const SIGNAL_WEIGHTS = {
+    [SignalType.ACCEPT]: 0.5,
+    [SignalType.DISMISS]: -0.3,
+    [SignalType.USAGE_DAILY]: 1.0,
+    [SignalType.USAGE_WEEKLY]: 0.3,
+    [SignalType.ABANDONED]: -0.7,
+    [SignalType.UNINSTALL]: -1.0,
+};
+/**
+ * Reason for dismissing a recommendation
+ */
+export var DismissReason;
+(function (DismissReason) {
+    /** Not relevant to current work */
+    DismissReason["NOT_RELEVANT"] = "not_relevant";
+    /** Already have similar functionality */
+    DismissReason["DUPLICATE"] = "duplicate";
+    /** Don't trust the source */
+    DismissReason["TRUST_ISSUE"] = "trust_issue";
+    /** Too complex/heavyweight */
+    DismissReason["TOO_COMPLEX"] = "too_complex";
+    /** No specific reason */
+    DismissReason["OTHER"] = "other";
+})(DismissReason || (DismissReason = {}));
+/**
+ * Skill category enum (aligned with skill schema)
+ */
+export var SkillCategory;
+(function (SkillCategory) {
+    SkillCategory["GIT"] = "git";
+    SkillCategory["TESTING"] = "testing";
+    SkillCategory["DOCUMENTATION"] = "documentation";
+    SkillCategory["DEVOPS"] = "devops";
+    SkillCategory["FRONTEND"] = "frontend";
+    SkillCategory["BACKEND"] = "backend";
+    SkillCategory["DATABASE"] = "database";
+    SkillCategory["SECURITY"] = "security";
+    SkillCategory["PRODUCTIVITY"] = "productivity";
+    SkillCategory["ANALYSIS"] = "analysis";
+})(SkillCategory || (SkillCategory = {}));
+/**
+ * Default learning configuration
+ */
+export const DEFAULT_LEARNING_CONFIG = {
+    learning_rate: 0.1,
+    decay_factor: 0.95,
+    min_signals_threshold: 5,
+    weight_bounds: {
+        min: -2.0,
+        max: 2.0,
+    },
+    signal_retention_days: 90,
+};
+/**
+ * Cold start default weights (before personalization)
+ * Based on aggregate popularity data
+ */
+export const COLD_START_WEIGHTS = {
+    category_weights: {
+        [SkillCategory.TESTING]: 0.3,
+        [SkillCategory.GIT]: 0.3,
+        [SkillCategory.DEVOPS]: 0.2,
+        [SkillCategory.DOCUMENTATION]: 0.1,
+        [SkillCategory.FRONTEND]: 0.2,
+        [SkillCategory.BACKEND]: 0.2,
+    },
+    trust_tier_weights: {
+        verified: 0.2,
+        community: 0.0,
+        standard: -0.1,
+        unverified: -0.3,
+    },
+};
+//# sourceMappingURL=types.js.map

package/dist/src/learning/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/learning/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;GAEG;AACH,MAAM,CAAN,IAAY,UAaX;AAbD,WAAY,UAAU;IACpB,oDAAoD;IACpD,+BAAiB,CAAA;IACjB,+CAA+C;IAC/C,iCAAmB,CAAA;IACnB,uDAAuD;IACvD,yCAA2B,CAAA;IAC3B,sDAAsD;IACtD,2CAA6B,CAAA;IAC7B,gDAAgD;IAChD,qCAAuB,CAAA;IACvB,iDAAiD;IACjD,qCAAuB,CAAA;AACzB,CAAC,EAbW,UAAU,KAAV,UAAU,QAarB;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAyC;IAClE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,GAAG;IACxB,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG;IAC1B,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,GAAG;IAC7B,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,GAAG;IAC9B,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG;IAC5B,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG;CACpB,CAAA;AAEV;;GAEG;AACH,MAAM,CAAN,IAAY,aAWX;AAXD,WAAY,aAAa;IACvB,mCAAmC;IACnC,8CAA6B,CAAA;IAC7B,yCAAyC;IACzC,wCAAuB,CAAA;IACvB,6BAA6B;IAC7B,4CAA2B,CAAA;IAC3B,8BAA8B;IAC9B,4CAA2B,CAAA;IAC3B,yBAAyB;IACzB,gCAAe,CAAA;AACjB,CAAC,EAXW,aAAa,KAAb,aAAa,QAWxB;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,aAWX;AAXD,WAAY,aAAa;IACvB,4BAAW,CAAA;IACX,oCAAmB,CAAA;IACnB,gDAA+B,CAAA;IAC/B,kCAAiB,CAAA;IACjB,sCAAqB,CAAA;IACrB,oCAAmB,CAAA;IACnB,sCAAqB,CAAA;IACrB,sCAAqB,CAAA;IACrB,8CAA6B,CAAA;IAC7B,sCAAqB,CAAA;AACvB,CAAC,EAXW,aAAa,KAAb,aAAa,QAWxB;AAgJD;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAA6B;IAC/D,aAAa,EAAE,GAAG;IAClB,YAAY,EAAE,IAAI;IAClB,qBAAqB,EAAE,CAAC;IACxB,aAAa,EAAE;QACb,GAAG,EAAE,CAAC,GAAG;QACT,GAAG,EAAE,GAAG;KACT;IACD,qBAAqB,EAAE,EAAE;CACjB,CAAA;AAEV;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAG1B;IACH,gBAAgB,EAAE;QAChB,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,GAAG;QAC5B,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,GAAG;QACxB,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,GAAG;QAC3B,CAAC,aAAa,CAAC,aAAa,CAAC,EAAE,GAAG;QAClC,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE,GAAG;QAC7B,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,GAAG;KAC7B;IACD,kBAAkB,EAAE;QAClB,QAAQ,EAAE,GAAG;QACb,SAAS,EAAE,GAAG;QACd,QAAQ,EAAE,CAAC,GAAG;QACd,UAAU,EAAE,CAAC,GAAG;KACjB;CACO,CAAA"}

package/dist/src/matching/OverlapDetector.d.ts

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview Trigger phrase overlap detection for skills
+ * @module @skillsmith/core/matching/OverlapDetector
+ * @see SMI-604: Trigger phrase overlap detection
+ *
+ * Detects similarity between skill trigger phrases to prevent
+ * recommending skills that overlap too much with installed ones.
+ *
+ * @example
+ * const detector = new OverlapDetector({ useFallback: true });
+ * const overlap = await detector.detectOverlap(skill1, skill2);
+ * if (overlap.overlapScore > 0.8) {
+ *   console.log('Skills are too similar:', overlap.overlappingPhrases);
+ * }
+ */
+import { type EmbeddingServiceOptions } from '../embeddings/index.js';
+/**
+ * Skill with trigger phrases for overlap detection
+ */
+export interface TriggerPhraseSkill {
+    /** Unique skill identifier */
+    id: string;
+    /** Skill display name */
+    name: string;
+    /** Trigger phrases that activate this skill */
+    triggerPhrases: string[];
+}
+/**
+ * Result of overlap detection between two skills
+ */
+export interface OverlapResult {
+    /** First skill ID */
+    skillId1: string;
+    /** Second skill ID */
+    skillId2: string;
+    /** Overall overlap score (0-1) */
+    overlapScore: number;
+    /** Specific phrases that overlap */
+    overlappingPhrases: Array<{
+        phrase1: string;
+        phrase2: string;
+        similarity: number;
+    }>;
+    /** Whether skills are considered duplicates */
+    isDuplicate: boolean;
+}
+/**
+ * Result of filtering skills by overlap
+ */
+export interface FilteredSkillsResult {
+    /** Skills that passed the overlap filter */
+    accepted: TriggerPhraseSkill[];
+    /** Skills that were rejected due to overlap */
+    rejected: Array<{
+        skill: TriggerPhraseSkill;
+        overlapsWith: string;
+        overlapScore: number;
+    }>;
+}
+/**
+ * Options for OverlapDetector
+ */
+export interface OverlapDetectorOptions extends EmbeddingServiceOptions {
+    /** Similarity threshold for phrase matching (0-1, default 0.75) */
+    phraseThreshold?: number;
+    /** Overall overlap threshold for skill rejection (0-1, default 0.6) */
+    overlapThreshold?: number;
+    /** Whether to use exact string matching in addition to semantic (default true) */
+    useExactMatch?: boolean;
+}
+/**
+ * Detects overlap between skill trigger phrases.
+ *
+ * Uses semantic similarity to identify skills that respond to
+ * similar user inputs, preventing confusing recommendations.
+ *
+ * @example
+ * const detector = new OverlapDetector({ overlapThreshold: 0.7 });
+ * const result = await detector.filterByOverlap(candidates, installed);
+ * // Use result.accepted for recommendations
+ */
+export declare class OverlapDetector {
+    private embeddingService;
+    private phraseEmbeddings;
+    private readonly phraseThreshold;
+    private readonly overlapThreshold;
+    private readonly useExactMatch;
+    constructor(options?: OverlapDetectorOptions);
+    /**
+     * Check if detector is using fallback mode
+     */
+    isUsingFallback(): boolean;
+    /**
+     * Detect overlap between two skills.
+     *
+     * @param skill1 - First skill
+     * @param skill2 - Second skill
+     * @returns Detailed overlap analysis
+     */
+    detectOverlap(skill1: TriggerPhraseSkill, skill2: TriggerPhraseSkill): Promise<OverlapResult>;
+    /**
+     * Check for exact string match (case-insensitive, normalized)
+     */
+    private isExactMatch;
+    /**
+     * Get or compute embedding for a phrase
+     */
+    private getPhraseEmbedding;
+    /**
+     * Filter candidate skills by overlap with installed skills.
+     *
+     * Removes candidates that have too much trigger phrase overlap
+     * with already installed skills.
+     *
+     * @param candidates - Skills to consider for recommendation
+     * @param installed - Currently installed skills
+     * @returns Filtered results with accepted and rejected skills
+     *
+     * @example
+     * const result = await detector.filterByOverlap(candidates, installed);
+     * console.log(`Accepted: ${result.accepted.length}`);
+     * console.log(`Rejected: ${result.rejected.length}`);
+     */
+    filterByOverlap(candidates: TriggerPhraseSkill[], installed: TriggerPhraseSkill[]): Promise<FilteredSkillsResult>;
+    /**
+     * Find all overlapping skill pairs in a set.
+     *
+     * Useful for auditing a skill library for potential conflicts.
+     *
+     * @param skills - Skills to check for overlaps
+     * @returns List of overlapping pairs
+     */
+    findAllOverlaps(skills: TriggerPhraseSkill[]): Promise<OverlapResult[]>;
+    /**
+     * Get overlap threshold
+     */
+    getOverlapThreshold(): number;
+    /**
+     * Get phrase similarity threshold
+     */
+    getPhraseThreshold(): number;
+    /**
+     * Clear cached embeddings
+     */
+    clear(): void;
+    /**
+     * Close resources
+     */
+    close(): void;
+}
+export default OverlapDetector;
+//# sourceMappingURL=OverlapDetector.d.ts.map

package/dist/src/matching/OverlapDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OverlapDetector.d.ts","sourceRoot":"","sources":["../../../src/matching/OverlapDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAoB,KAAK,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AAEvF;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,+CAA+C;IAC/C,cAAc,EAAE,MAAM,EAAE,CAAA;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,qBAAqB;IACrB,QAAQ,EAAE,MAAM,CAAA;IAChB,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,kCAAkC;IAClC,YAAY,EAAE,MAAM,CAAA;IACpB,oCAAoC;IACpC,kBAAkB,EAAE,KAAK,CAAC;QACxB,OAAO,EAAE,MAAM,CAAA;QACf,OAAO,EAAE,MAAM,CAAA;QACf,UAAU,EAAE,MAAM,CAAA;KACnB,CAAC,CAAA;IACF,+CAA+C;IAC/C,WAAW,EAAE,OAAO,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,4CAA4C;IAC5C,QAAQ,EAAE,kBAAkB,EAAE,CAAA;IAC9B,+CAA+C;IAC/C,QAAQ,EAAE,KAAK,CAAC;QACd,KAAK,EAAE,kBAAkB,CAAA;QACzB,YAAY,EAAE,MAAM,CAAA;QACpB,YAAY,EAAE,MAAM,CAAA;KACrB,CAAC,CAAA;CACH;AAED;;GAEG;AACH,MAAM,WAAW,sBAAuB,SAAQ,uBAAuB;IACrE,mEAAmE;IACnE,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,uEAAuE;IACvE,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,kFAAkF;IAClF,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,gBAAgB,CAAkB;IAC1C,OAAO,CAAC,gBAAgB,CAAuC;IAC/D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAQ;IACxC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAQ;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;gBAE3B,OAAO,GAAE,sBAA2B;IAOhD;;OAEG;IACH,eAAe,IAAI,OAAO;IAI1B;;;;;;OAMG;IACG,aAAa,CACjB,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,aAAa,CAAC;IA0DzB;;OAEG;IACH,OAAO,CAAC,YAAY;IAKpB;;OAEG;YACW,kBAAkB;IAWhC;;;;;;;;;;;;;;OAcG;IACG,eAAe,CACnB,UAAU,EAAE,kBAAkB,EAAE,EAChC,SAAS,EAAE,kBAAkB,EAAE,GAC9B,OAAO,CAAC,oBAAoB,CAAC;IA0ChC;;;;;;;OAOG;IACG,eAAe,CAAC,MAAM,EAAE,kBAAkB,EAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAmB7E;;OAEG;IACH,mBAAmB,IAAI,MAAM;IAI7B;;OAEG;IACH,kBAAkB,IAAI,MAAM;IAI5B;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,KAAK,IAAI,IAAI;CAId;AAED,eAAe,eAAe,CAAA"}

package/dist/src/matching/OverlapDetector.js

@@ -0,0 +1,218 @@
+/**
+ * @fileoverview Trigger phrase overlap detection for skills
+ * @module @skillsmith/core/matching/OverlapDetector
+ * @see SMI-604: Trigger phrase overlap detection
+ *
+ * Detects similarity between skill trigger phrases to prevent
+ * recommending skills that overlap too much with installed ones.
+ *
+ * @example
+ * const detector = new OverlapDetector({ useFallback: true });
+ * const overlap = await detector.detectOverlap(skill1, skill2);
+ * if (overlap.overlapScore > 0.8) {
+ *   console.log('Skills are too similar:', overlap.overlappingPhrases);
+ * }
+ */
+import { EmbeddingService } from '../embeddings/index.js';
+/**
+ * Detects overlap between skill trigger phrases.
+ *
+ * Uses semantic similarity to identify skills that respond to
+ * similar user inputs, preventing confusing recommendations.
+ *
+ * @example
+ * const detector = new OverlapDetector({ overlapThreshold: 0.7 });
+ * const result = await detector.filterByOverlap(candidates, installed);
+ * // Use result.accepted for recommendations
+ */
+export class OverlapDetector {
+    embeddingService;
+    phraseEmbeddings = new Map();
+    phraseThreshold;
+    overlapThreshold;
+    useExactMatch;
+    constructor(options = {}) {
+        this.embeddingService = new EmbeddingService(options);
+        this.phraseThreshold = options.phraseThreshold ?? 0.75;
+        this.overlapThreshold = options.overlapThreshold ?? 0.6;
+        this.useExactMatch = options.useExactMatch ?? true;
+    }
+    /**
+     * Check if detector is using fallback mode
+     */
+    isUsingFallback() {
+        return this.embeddingService.isUsingFallback();
+    }
+    /**
+     * Detect overlap between two skills.
+     *
+     * @param skill1 - First skill
+     * @param skill2 - Second skill
+     * @returns Detailed overlap analysis
+     */
+    async detectOverlap(skill1, skill2) {
+        const overlappingPhrases = [];
+        // Get embeddings for all phrases
+        for (const phrase1 of skill1.triggerPhrases) {
+            for (const phrase2 of skill2.triggerPhrases) {
+                // Check exact match first
+                if (this.useExactMatch && this.isExactMatch(phrase1, phrase2)) {
+                    overlappingPhrases.push({
+                        phrase1,
+                        phrase2,
+                        similarity: 1.0,
+                    });
+                    continue;
+                }
+                // Check semantic similarity
+                const embedding1 = await this.getPhraseEmbedding(phrase1);
+                const embedding2 = await this.getPhraseEmbedding(phrase2);
+                const similarity = this.embeddingService.cosineSimilarity(embedding1, embedding2);
+                if (similarity >= this.phraseThreshold) {
+                    overlappingPhrases.push({
+                        phrase1,
+                        phrase2,
+                        similarity: Math.round(similarity * 100) / 100,
+                    });
+                }
+            }
+        }
+        // Calculate overall overlap score based on unique phrases that overlap
+        // Count unique phrases from skill1 that have at least one match in skill2
+        const overlappingFromSkill1 = new Set(overlappingPhrases.map((p) => p.phrase1));
+        const overlappingFromSkill2 = new Set(overlappingPhrases.map((p) => p.phrase2));
+        // Calculate the overlap ratio for each skill
+        const ratio1 = skill1.triggerPhrases.length > 0
+            ? overlappingFromSkill1.size / skill1.triggerPhrases.length
+            : 0;
+        const ratio2 = skill2.triggerPhrases.length > 0
+            ? overlappingFromSkill2.size / skill2.triggerPhrases.length
+            : 0;
+        // Use the average of both ratios for a balanced score
+        const overlapScore = (ratio1 + ratio2) / 2;
+        return {
+            skillId1: skill1.id,
+            skillId2: skill2.id,
+            overlapScore: Math.round(overlapScore * 100) / 100,
+            overlappingPhrases,
+            isDuplicate: overlapScore >= this.overlapThreshold,
+        };
+    }
+    /**
+     * Check for exact string match (case-insensitive, normalized)
+     */
+    isExactMatch(phrase1, phrase2) {
+        const normalize = (s) => s.toLowerCase().trim().replace(/\s+/g, ' ');
+        return normalize(phrase1) === normalize(phrase2);
+    }
+    /**
+     * Get or compute embedding for a phrase
+     */
+    async getPhraseEmbedding(phrase) {
+        const cacheKey = phrase.toLowerCase().trim();
+        if (!this.phraseEmbeddings.has(cacheKey)) {
+            const embedding = await this.embeddingService.embed(phrase);
+            this.phraseEmbeddings.set(cacheKey, embedding);
+        }
+        return this.phraseEmbeddings.get(cacheKey);
+    }
+    /**
+     * Filter candidate skills by overlap with installed skills.
+     *
+     * Removes candidates that have too much trigger phrase overlap
+     * with already installed skills.
+     *
+     * @param candidates - Skills to consider for recommendation
+     * @param installed - Currently installed skills
+     * @returns Filtered results with accepted and rejected skills
+     *
+     * @example
+     * const result = await detector.filterByOverlap(candidates, installed);
+     * console.log(`Accepted: ${result.accepted.length}`);
+     * console.log(`Rejected: ${result.rejected.length}`);
+     */
+    async filterByOverlap(candidates, installed) {
+        const accepted = [];
+        const rejected = [];
+        for (const candidate of candidates) {
+            let highestOverlap = 0;
+            let overlapsWith = '';
+            // Check overlap with each installed skill
+            for (const installedSkill of installed) {
+                const overlap = await this.detectOverlap(candidate, installedSkill);
+                if (overlap.overlapScore > highestOverlap) {
+                    highestOverlap = overlap.overlapScore;
+                    overlapsWith = installedSkill.id;
+                }
+            }
+            // Also check overlap with already accepted candidates
+            for (const acceptedSkill of accepted) {
+                const overlap = await this.detectOverlap(candidate, acceptedSkill);
+                if (overlap.overlapScore > highestOverlap) {
+                    highestOverlap = overlap.overlapScore;
+                    overlapsWith = acceptedSkill.id;
+                }
+            }
+            if (highestOverlap >= this.overlapThreshold) {
+                rejected.push({
+                    skill: candidate,
+                    overlapsWith,
+                    overlapScore: highestOverlap,
+                });
+            }
+            else {
+                accepted.push(candidate);
+            }
+        }
+        return { accepted, rejected };
+    }
+    /**
+     * Find all overlapping skill pairs in a set.
+     *
+     * Useful for auditing a skill library for potential conflicts.
+     *
+     * @param skills - Skills to check for overlaps
+     * @returns List of overlapping pairs
+     */
+    async findAllOverlaps(skills) {
+        const overlaps = [];
+        for (let i = 0; i < skills.length; i++) {
+            for (let j = i + 1; j < skills.length; j++) {
+                const result = await this.detectOverlap(skills[i], skills[j]);
+                if (result.overlappingPhrases.length > 0) {
+                    overlaps.push(result);
+                }
+            }
+        }
+        // Sort by overlap score descending
+        overlaps.sort((a, b) => b.overlapScore - a.overlapScore);
+        return overlaps;
+    }
+    /**
+     * Get overlap threshold
+     */
+    getOverlapThreshold() {
+        return this.overlapThreshold;
+    }
+    /**
+     * Get phrase similarity threshold
+     */
+    getPhraseThreshold() {
+        return this.phraseThreshold;
+    }
+    /**
+     * Clear cached embeddings
+     */
+    clear() {
+        this.phraseEmbeddings.clear();
+    }
+    /**
+     * Close resources
+     */
+    close() {
+        this.embeddingService.close();
+        this.clear();
+    }
+}
+export default OverlapDetector;
+//# sourceMappingURL=OverlapDetector.js.map

package/dist/src/matching/OverlapDetector.js.map

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

package/dist/src/matching/SkillMatcher.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @fileoverview Semantic skill matching using embeddings
+ * @module @skillsmith/core/matching/SkillMatcher
+ * @see SMI-602: Implement recommend_skills MCP tool
+ *
+ * Provides semantic similarity matching between skills using
+ * the EmbeddingService for vector-based comparisons.
+ *
+ * @example
+ * const matcher = new SkillMatcher({ useFallback: true });
+ * const matches = await matcher.findSimilarSkills('react testing', skills, 5);
+ */
+import { type EmbeddingServiceOptions } from '../embeddings/index.js';
+/**
+ * Skill data for matching
+ */
+export interface MatchableSkill {
+    /** Unique skill identifier */
+    id: string;
+    /** Skill display name */
+    name: string;
+    /** Skill description */
+    description: string;
+    /** Optional trigger phrases for overlap detection */
+    triggerPhrases?: string[];
+    /** Optional keywords for keyword-based fallback */
+    keywords?: string[];
+    /** Optional quality score (0-100) */
+    qualityScore?: number;
+}
+/**
+ * Result of a skill match
+ */
+export interface SkillMatchResult {
+    /** Matched skill */
+    skill: MatchableSkill;
+    /** Semantic similarity score (0-1) */
+    similarityScore: number;
+    /** Why this skill matched */
+    matchReason: string;
+}
+/**
+ * Options for SkillMatcher
+ */
+export interface SkillMatcherOptions extends EmbeddingServiceOptions {
+    /** Minimum similarity threshold (0-1, default 0.3) */
+    minSimilarity?: number;
+    /** Quality score weight (0-1, default 0.3) */
+    qualityWeight?: number;
+}
+/**
+ * Semantic skill matcher using embeddings.
+ *
+ * Finds skills similar to a query using vector similarity,
+ * with optional quality score boosting.
+ *
+ * @example
+ * const matcher = new SkillMatcher({ useFallback: true });
+ * await matcher.initialize(skills);
+ * const results = await matcher.findSimilarSkills('react testing', skills);
+ */
+export declare class SkillMatcher {
+    private embeddingService;
+    private skillEmbeddings;
+    private initialized;
+    private readonly minSimilarity;
+    private readonly qualityWeight;
+    constructor(options?: SkillMatcherOptions);
+    /**
+     * Check if matcher is using fallback mode
+     */
+    isUsingFallback(): boolean;
+    /**
+     * Initialize skill embeddings for a set of skills.
+     * Call this before matching for best performance.
+     */
+    initialize(skills: MatchableSkill[]): Promise<void>;
+    /**
+     * Convert skill to text for embedding
+     */
+    private skillToText;
+    /**
+     * Find skills similar to a query string.
+     *
+     * @param query - Search query or context description
+     * @param skills - Pool of skills to search
+     * @param limit - Maximum results to return
+     * @returns Ranked list of matching skills
+     *
+     * @example
+     * const matches = await matcher.findSimilarSkills(
+     *   'React TypeScript frontend testing',
+     *   availableSkills,
+     *   5
+     * );
+     */
+    findSimilarSkills(query: string, skills: MatchableSkill[], limit?: number): Promise<SkillMatchResult[]>;
+    /**
+     * Find skills similar to a set of installed skills.
+     *
+     * @param installedSkills - Currently installed skills
+     * @param candidateSkills - Pool of skills to recommend from
+     * @param limit - Maximum results
+     * @returns Ranked list of recommended skills
+     */
+    findComplementarySkills(installedSkills: MatchableSkill[], candidateSkills: MatchableSkill[], limit?: number): Promise<SkillMatchResult[]>;
+    /**
+     * Generate a human-readable match reason
+     */
+    private generateMatchReason;
+    /**
+     * Get embedding dimension
+     */
+    getEmbeddingDimension(): number;
+    /**
+     * Clear cached embeddings
+     */
+    clear(): void;
+    /**
+     * Close resources
+     */
+    close(): void;
+}
+export default SkillMatcher;
+//# sourceMappingURL=SkillMatcher.d.ts.map

package/dist/src/matching/SkillMatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SkillMatcher.d.ts","sourceRoot":"","sources":["../../../src/matching/SkillMatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAoB,KAAK,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AAEvF;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAA;IACnB,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;IACzB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,qCAAqC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oBAAoB;IACpB,KAAK,EAAE,cAAc,CAAA;IACrB,sCAAsC;IACtC,eAAe,EAAE,MAAM,CAAA;IACvB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,uBAAuB;IAClE,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,8CAA8C;IAC9C,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,gBAAgB,CAAkB;IAC1C,OAAO,CAAC,eAAe,CAAuC;IAC9D,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;gBAE1B,OAAO,GAAE,mBAAwB;IAM7C;;OAEG;IACH,eAAe,IAAI,OAAO;IAI1B;;;OAGG;IACG,UAAU,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAezD;;OAEG;IACH,OAAO,CAAC,WAAW;IAcnB;;;;;;;;;;;;;;OAcG;IACG,iBAAiB,CACrB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,cAAc,EAAE,EACxB,KAAK,GAAE,MAAW,GACjB,OAAO,CAAC,gBAAgB,EAAE,CAAC;IA6C9B;;;;;;;OAOG;IACG,uBAAuB,CAC3B,eAAe,EAAE,cAAc,EAAE,EACjC,eAAe,EAAE,cAAc,EAAE,EACjC,KAAK,GAAE,MAAW,GACjB,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAwB9B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAyC3B;;OAEG;IACH,qBAAqB,IAAI,MAAM;IAI/B;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,KAAK,IAAI,IAAI;CAId;AAED,eAAe,YAAY,CAAA"}