@skillsmith/core 0.1.0

package/dist/src/learning/interfaces.d.ts

@@ -0,0 +1,338 @@
+/**
+ * @fileoverview Service interfaces for Recommendation Learning Loop
+ * @module @skillsmith/core/learning/interfaces
+ * @see docs/phase4/epic1/recommendation-learning-loop-design.md
+ *
+ * Defines contracts for:
+ * - SignalCollector: Recording user interactions
+ * - PreferenceLearner: Learning from signals
+ * - PrivacyManager: Data lifecycle management
+ * - PersonalizationEngine: Applying learned preferences
+ */
+import type { SignalEvent, SignalFilter, RecommendationContext, SignalMetadata, DismissReason, UserPreferenceProfile, LearningConfig, PersonalizedRecommendation, UserDataExport, AggregateStats } from './types.js';
+/**
+ * Service for collecting user interaction signals
+ *
+ * Responsibilities:
+ * - Record accept/dismiss/usage events
+ * - Store signals in local SQLite database
+ * - Query signals for learning algorithm
+ *
+ * @example
+ * ```typescript
+ * const collector = new SignalCollector(dbPath)
+ * await collector.recordAccept('anthropic/commit', {
+ *   installed_skills: ['anthropic/review-pr'],
+ *   original_score: 0.85
+ * })
+ * ```
+ */
+export interface ISignalCollector {
+    /**
+     * Record user accepting a recommendation
+     *
+     * @param skillId - Skill that was accepted
+     * @param context - Context when skill was recommended
+     * @param metadata - Optional metadata (timing, suggestion count)
+     * @throws {SkillsmithError} If database write fails
+     */
+    recordAccept(skillId: string, context: RecommendationContext, metadata?: SignalMetadata): Promise<void>;
+    /**
+     * Record user dismissing a recommendation
+     *
+     * @param skillId - Skill that was dismissed
+     * @param context - Context when skill was recommended
+     * @param reason - Optional reason for dismissal
+     * @throws {SkillsmithError} If database write fails
+     */
+    recordDismiss(skillId: string, context: RecommendationContext, reason?: DismissReason): Promise<void>;
+    /**
+     * Record skill usage event
+     *
+     * Called by usage tracker to record daily/weekly usage
+     *
+     * @param skillId - Skill that was used
+     * @param frequency - Usage frequency (daily or weekly)
+     * @throws {SkillsmithError} If database write fails
+     */
+    recordUsage(skillId: string, frequency: 'daily' | 'weekly'): Promise<void>;
+    /**
+     * Record skill abandonment (installed but never used)
+     *
+     * @param skillId - Skill that was abandoned
+     * @param daysSinceInstall - Days since installation
+     * @throws {SkillsmithError} If database write fails
+     */
+    recordAbandonment(skillId: string, daysSinceInstall: number): Promise<void>;
+    /**
+     * Record skill uninstallation
+     *
+     * @param skillId - Skill that was uninstalled
+     * @param daysSinceInstall - Days since installation
+     * @throws {SkillsmithError} If database write fails
+     */
+    recordUninstall(skillId: string, daysSinceInstall: number): Promise<void>;
+    /**
+     * Query signals with filtering
+     *
+     * @param filter - Filter criteria
+     * @param limit - Maximum results to return
+     * @returns Array of matching signal events
+     * @throws {SkillsmithError} If database query fails
+     */
+    getSignals(filter: SignalFilter, limit?: number): Promise<SignalEvent[]>;
+    /**
+     * Get total signal count
+     *
+     * @returns Total number of signals recorded
+     */
+    getSignalCount(): Promise<number>;
+    /**
+     * Get signals for specific skill
+     *
+     * @param skillId - Skill identifier
+     * @returns All signals for this skill
+     */
+    getSignalsForSkill(skillId: string): Promise<SignalEvent[]>;
+}
+/**
+ * Service for learning user preferences from signals
+ *
+ * Responsibilities:
+ * - Update preference weights based on signals
+ * - Apply time decay to old signals
+ * - Maintain weight bounds
+ * - Calculate personalized scores
+ *
+ * @example
+ * ```typescript
+ * const learner = new PreferenceLearner(config)
+ * const updatedProfile = await learner.updateProfile(
+ *   currentProfile,
+ *   newSignalEvent
+ * )
+ * ```
+ */
+export interface IPreferenceLearner {
+    /**
+     * Update user profile based on new signal
+     *
+     * Applies learning algorithm to adjust weights:
+     * - Category weights
+     * - Trust tier weights
+     * - Keyword weights
+     * - Negative patterns
+     *
+     * @param profile - Current user profile
+     * @param signal - New signal event to learn from
+     * @returns Updated profile with adjusted weights
+     */
+    updateProfile(profile: UserPreferenceProfile, signal: SignalEvent): Promise<UserPreferenceProfile>;
+    /**
+     * Batch update profile from multiple signals
+     *
+     * More efficient than individual updates for bulk processing
+     *
+     * @param profile - Current user profile
+     * @param signals - Array of signal events
+     * @returns Updated profile
+     */
+    batchUpdateProfile(profile: UserPreferenceProfile, signals: SignalEvent[]): Promise<UserPreferenceProfile>;
+    /**
+     * Apply time decay to weights
+     *
+     * Reduces influence of old signals to allow preference evolution
+     *
+     * @param profile - Current user profile
+     * @param decayFactor - Decay multiplier (0.8-1.0)
+     * @returns Profile with decayed weights
+     */
+    decayWeights(profile: UserPreferenceProfile, decayFactor?: number): Promise<UserPreferenceProfile>;
+    /**
+     * Calculate personalized score for a skill
+     *
+     * @param skillData - Skill metadata (category, keywords, etc.)
+     * @param baseScore - Base recommendation score [0-1]
+     * @param profile - User preference profile
+     * @returns Personalized recommendation with score breakdown
+     */
+    calculatePersonalizedScore(skillData: {
+        id: string;
+        category?: string;
+        trustTier?: string;
+        keywords?: string[];
+        triggerPhrases?: string[];
+    }, baseScore: number, profile: UserPreferenceProfile): PersonalizedRecommendation;
+    /**
+     * Get learning configuration
+     */
+    getConfig(): LearningConfig;
+    /**
+     * Update learning configuration
+     *
+     * @param config - Partial config to merge
+     */
+    setConfig(config: Partial<LearningConfig>): void;
+}
+/**
+ * Service for managing data privacy and lifecycle
+ *
+ * Responsibilities:
+ * - Purge old signals (retention policy)
+ * - Export user data (GDPR compliance)
+ * - Complete data wipe
+ * - Anonymize for analytics
+ *
+ * @example
+ * ```typescript
+ * const privacy = new PrivacyManager(dbPath)
+ * const deleted = await privacy.purgeOldSignals(90) // 90 day retention
+ * console.log(`Deleted ${deleted} old signals`)
+ * ```
+ */
+export interface IPrivacyManager {
+    /**
+     * Purge signals older than retention period
+     *
+     * @param retentionDays - Keep signals from last N days
+     * @returns Number of signals deleted
+     * @throws {SkillsmithError} If database operation fails
+     */
+    purgeOldSignals(retentionDays: number): Promise<number>;
+    /**
+     * Export all user data (GDPR-style)
+     *
+     * Includes:
+     * - User preference profile
+     * - All signal events
+     * - Aggregate statistics
+     *
+     * @returns Complete user data export
+     * @throws {SkillsmithError} If export fails
+     */
+    exportUserData(): Promise<UserDataExport>;
+    /**
+     * Complete data wipe (user request)
+     *
+     * Deletes:
+     * - All signals
+     * - User profile
+     * - Aggregate stats
+     *
+     * @returns Number of records deleted
+     * @throws {SkillsmithError} If wipe fails
+     */
+    wipeAllData(): Promise<number>;
+    /**
+     * Anonymize signals for aggregate analysis
+     *
+     * Strips all PII and creates aggregate statistics
+     *
+     * @returns Anonymized aggregate stats
+     */
+    anonymizeForAnalytics(): Promise<AggregateStats>;
+    /**
+     * Get current storage size
+     *
+     * @returns Database size in bytes
+     */
+    getStorageSize(): Promise<number>;
+    /**
+     * Verify no data leaks (for testing)
+     *
+     * Checks that no PII is in aggregate tables
+     *
+     * @returns True if privacy-preserving
+     */
+    verifyPrivacy(): Promise<boolean>;
+}
+/**
+ * Service for applying personalization to recommendations
+ *
+ * Responsibilities:
+ * - Load user profile
+ * - Apply personalized scoring
+ * - Handle cold start
+ * - Re-rank recommendations
+ *
+ * @example
+ * ```typescript
+ * const engine = new PersonalizationEngine(learner, profileStore)
+ * const personalized = await engine.personalizeRecommendations(
+ *   baseRecommendations,
+ *   userContext
+ * )
+ * ```
+ */
+export interface IPersonalizationEngine {
+    /**
+     * Personalize recommendation results
+     *
+     * @param baseRecommendations - Recommendations with base scores
+     * @param userId - User identifier (for profile lookup)
+     * @returns Re-ranked recommendations with personalized scores
+     */
+    personalizeRecommendations(baseRecommendations: Array<{
+        skill_id: string;
+        base_score: number;
+        skill_data: {
+            category?: string;
+            trustTier?: string;
+            keywords?: string[];
+        };
+    }>, userId?: string): Promise<PersonalizedRecommendation[]>;
+    /**
+     * Check if user has enough data for personalization
+     *
+     * @param userId - User identifier
+     * @returns True if personalization should be applied
+     */
+    shouldPersonalize(userId?: string): Promise<boolean>;
+    /**
+     * Get user preference profile
+     *
+     * @param userId - User identifier
+     * @returns User profile or default cold start profile
+     */
+    getUserProfile(userId?: string): Promise<UserPreferenceProfile>;
+    /**
+     * Reset to cold start (clear personalization)
+     *
+     * @param userId - User identifier
+     */
+    resetToDefault(userId?: string): Promise<void>;
+}
+/**
+ * Repository interface for user preference storage
+ *
+ * Abstraction over SQLite for testability
+ */
+export interface IUserPreferenceRepository {
+    /**
+     * Get user preference profile
+     *
+     * @param userId - User identifier (default: 'default')
+     * @returns Profile or null if not exists
+     */
+    getProfile(userId?: string): Promise<UserPreferenceProfile | null>;
+    /**
+     * Save user preference profile
+     *
+     * @param profile - Profile to save
+     * @param userId - User identifier (default: 'default')
+     */
+    saveProfile(profile: UserPreferenceProfile, userId?: string): Promise<void>;
+    /**
+     * Delete user profile
+     *
+     * @param userId - User identifier
+     */
+    deleteProfile(userId?: string): Promise<void>;
+    /**
+     * Check if profile exists
+     *
+     * @param userId - User identifier
+     */
+    exists(userId?: string): Promise<boolean>;
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/src/learning/interfaces.d.ts.map

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

package/dist/src/learning/interfaces.js

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Service interfaces for Recommendation Learning Loop
+ * @module @skillsmith/core/learning/interfaces
+ * @see docs/phase4/epic1/recommendation-learning-loop-design.md
+ *
+ * Defines contracts for:
+ * - SignalCollector: Recording user interactions
+ * - PreferenceLearner: Learning from signals
+ * - PrivacyManager: Data lifecycle management
+ * - PersonalizationEngine: Applying learned preferences
+ */
+export {};
+//# sourceMappingURL=interfaces.js.map

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

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

package/dist/src/learning/types.d.ts

@@ -0,0 +1,284 @@
+/**
+ * @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 declare enum SignalType {
+    /** User accepted and installed recommended skill */
+    ACCEPT = "accept",
+    /** User explicitly dismissed recommendation */
+    DISMISS = "dismiss",
+    /** User actively uses installed skill (daily usage) */
+    USAGE_DAILY = "usage_daily",
+    /** User rarely uses installed skill (weekly usage) */
+    USAGE_WEEKLY = "usage_weekly",
+    /** Skill installed but never used (30+ days) */
+    ABANDONED = "abandoned",
+    /** User uninstalled previously accepted skill */
+    UNINSTALL = "uninstall"
+}
+/**
+ * Signal strength weights for learning algorithm
+ * Range: [-1.0, 1.0] where:
+ * - Positive = user preference signal
+ * - Negative = user rejection signal
+ */
+export declare const SIGNAL_WEIGHTS: Readonly<Record<SignalType, number>>;
+/**
+ * Reason for dismissing a recommendation
+ */
+export declare enum DismissReason {
+    /** Not relevant to current work */
+    NOT_RELEVANT = "not_relevant",
+    /** Already have similar functionality */
+    DUPLICATE = "duplicate",
+    /** Don't trust the source */
+    TRUST_ISSUE = "trust_issue",
+    /** Too complex/heavyweight */
+    TOO_COMPLEX = "too_complex",
+    /** No specific reason */
+    OTHER = "other"
+}
+/**
+ * Skill category enum (aligned with skill schema)
+ */
+export declare enum SkillCategory {
+    GIT = "git",
+    TESTING = "testing",
+    DOCUMENTATION = "documentation",
+    DEVOPS = "devops",
+    FRONTEND = "frontend",
+    BACKEND = "backend",
+    DATABASE = "database",
+    SECURITY = "security",
+    PRODUCTIVITY = "productivity",
+    ANALYSIS = "analysis"
+}
+/**
+ * Context when skill was recommended
+ */
+export interface RecommendationContext {
+    /** Skills installed at recommendation time */
+    installed_skills: string[];
+    /** Project context used for recommendation */
+    project_context?: string;
+    /** Similarity score at recommendation time */
+    original_score: number;
+    /** Trust tier of recommended skill */
+    trust_tier?: string;
+    /** Category of recommended skill */
+    category?: string;
+}
+/**
+ * Optional metadata for signal events
+ */
+export interface SignalMetadata {
+    /** Time between recommendation and action (ms) */
+    time_to_action?: number;
+    /** Number of times skill was suggested before action */
+    suggestion_count?: number;
+    /** Additional context-specific data */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Individual signal event stored in database
+ */
+export interface SignalEvent {
+    /** Unique event ID (UUID) */
+    id: string;
+    /** Signal type */
+    type: SignalType;
+    /** Skill that was recommended/interacted with */
+    skill_id: string;
+    /** Unix timestamp (ms) of event */
+    timestamp: number;
+    /** Recommendation context when skill was suggested */
+    context: RecommendationContext;
+    /** Optional metadata */
+    metadata?: SignalMetadata;
+    /** Dismiss reason (only for DISMISS signals) */
+    dismiss_reason?: DismissReason;
+}
+/**
+ * Filter for querying signal events
+ */
+export interface SignalFilter {
+    /** Filter by skill ID */
+    skill_id?: string;
+    /** Filter by signal type */
+    type?: SignalType | SignalType[];
+    /** Filter by time range */
+    time_range?: {
+        start: number;
+        end: number;
+    };
+    /** Filter by category */
+    category?: SkillCategory;
+}
+/**
+ * User-specific preference profile (local storage only)
+ * PRIVACY: This data never leaves the local machine
+ */
+export interface UserPreferenceProfile {
+    /** Profile schema version for migrations */
+    version: number;
+    /** Last updated timestamp (ms) */
+    last_updated: number;
+    /** Total signals collected */
+    signal_count: number;
+    /** Category preferences learned from signals
+     * Range: [-2.0, 2.0] where:
+     * - Positive = user prefers this category
+     * - Negative = user avoids this category
+     */
+    category_weights: Partial<Record<SkillCategory, number>>;
+    /** Trust tier preferences
+     * Range: [-2.0, 2.0]
+     */
+    trust_tier_weights: Record<string, number>;
+    /** Keyword/tag preferences
+     * Range: [-2.0, 2.0]
+     */
+    keyword_weights: Record<string, number>;
+    /** Anti-preferences (things user consistently dismisses) */
+    negative_patterns: {
+        /** Keywords user doesn't like */
+        keywords: string[];
+        /** Categories user avoids */
+        categories: SkillCategory[];
+        /** Specific skills user explicitly doesn't want */
+        skill_ids: string[];
+    };
+    /** Usage pattern insights */
+    usage_patterns: {
+        /** Average time from install to first use (ms) */
+        avg_time_to_first_use_ms: number;
+        /** Percentage of accepted skills actually used (0-1) */
+        utilization_rate: number;
+        /** Most used skill categories (ordered by frequency) */
+        top_categories: SkillCategory[];
+    };
+}
+/**
+ * Learning hyperparameters (tunable)
+ */
+export interface LearningConfig {
+    /** Base learning rate for weight updates (default: 0.1)
+     * Range: [0.01, 0.5]
+     */
+    learning_rate: number;
+    /** Time decay factor for old signals (default: 0.95/month)
+     * Range: [0.8, 1.0] where 1.0 = no decay
+     */
+    decay_factor: number;
+    /** Minimum signals before personalization kicks in */
+    min_signals_threshold: number;
+    /** Weight clipping bounds to prevent extreme values */
+    weight_bounds: {
+        min: number;
+        max: number;
+    };
+    /** Data retention period (days) */
+    signal_retention_days: number;
+}
+/**
+ * Default learning configuration
+ */
+export declare const DEFAULT_LEARNING_CONFIG: Readonly<LearningConfig>;
+/**
+ * Cold start default weights (before personalization)
+ * Based on aggregate popularity data
+ */
+export declare const COLD_START_WEIGHTS: Readonly<{
+    category_weights: Partial<Record<SkillCategory, number>>;
+    trust_tier_weights: Record<string, number>;
+}>;
+/**
+ * Personalized recommendation result
+ */
+export interface PersonalizedRecommendation {
+    /** Skill identifier */
+    skill_id: string;
+    /** Base similarity score [0-1] */
+    base_score: number;
+    /** Personalized score after learning adjustments [0-1] */
+    personalized_score: number;
+    /** Whether personalization was applied */
+    personalization_applied: boolean;
+    /** Breakdown of score adjustments */
+    score_breakdown: {
+        category_boost: number;
+        trust_boost: number;
+        keyword_boost: number;
+        anti_penalty: number;
+    };
+}
+/**
+ * Aggregate statistics (anonymized, no PII)
+ */
+export interface AggregateStats {
+    /** Date (YYYY-MM-DD) */
+    date: string;
+    /** Total signals recorded */
+    total_signals: number;
+    /** Breakdown by signal type */
+    signal_counts: Partial<Record<SignalType, number>>;
+    /** Average accept rate */
+    avg_accept_rate: number;
+    /** Average utilization rate */
+    avg_utilization_rate: number;
+    /** Popular categories */
+    popular_categories: Array<{
+        category: SkillCategory;
+        count: number;
+    }>;
+}
+/**
+ * User data export (GDPR-style)
+ */
+export interface UserDataExport {
+    /** Export timestamp */
+    exported_at: number;
+    /** Profile version */
+    version: number;
+    /** User preference profile */
+    profile: UserPreferenceProfile;
+    /** All signal events */
+    signals: SignalEvent[];
+    /** Aggregate stats */
+    stats: AggregateStats[];
+}
+/**
+ * Events emitted by learning system
+ */
+export interface LearningEvents {
+    /** Signal recorded successfully */
+    'signal:recorded': {
+        signal_id: string;
+        type: SignalType;
+        skill_id: string;
+    };
+    /** Profile updated */
+    'profile:updated': {
+        signal_count: number;
+        personalization_active: boolean;
+    };
+    /** Data purged (privacy cleanup) */
+    'data:purged': {
+        signals_deleted: number;
+        retention_days: number;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/learning/types.d.ts.map

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