@skillsmith/core 0.4.0 → 0.4.2

package/dist/src/routing/SONARouter.d.ts

@@ -6,46 +6,12 @@
  * Routes MCP tool requests through an 8-expert MoE (Mixture of Experts)
  * network to optimize tool execution based on accuracy requirements,
  * latency constraints, and load distribution.
- *
- * Features:
- * - O(1) routing decisions with LRU caching
- * - V3 MoE integration with fallback to local scoring
- * - Adaptive load balancing across experts
- * - Health monitoring and circuit breaker patterns
- * - Feature flags for gradual rollout
- * - Prometheus-compatible metrics
- *
- * Performance targets:
- * - 2.8-4.4x speed improvement
- * - <5ms routing overhead (P95)
- * - >60% cache hit rate
- *
- * @example
- * ```typescript
- * const router = new SONARouter()
- * await router.initialize()
- *
- * const decision = await router.route({
- *   requestId: 'req-123',
- *   tool: 'search',
- *   arguments: { query: 'testing skills' },
- *   timestamp: new Date(),
- * })
- *
- * console.log(decision.expertId) // 'accuracy-semantic'
- * console.log(decision.confidence) // 0.92
- * ```
  */
-import type { ExpertDefinition, ExpertId, ExpertState, ExpertStatus, RoutingDecision, SONAMetrics, SONARouterConfig, ToolRequest, ToolResponse, ToolType } from './types.js';
+import type { ExpertDefinition, ExpertId, ExpertState, ExpertStatus, RoutingDecision, SONAMetrics, SONARouterConfig, ToolRequest, ToolResponse } from './types.js';
+export { LRUCache, MetricsCollector, shouldUseSONARouting, isHighConfidenceDecision, usedFallback, } from './SONARouter.helpers.js';
+export type { V3RoutingResult, V3MoERouter, V3RoutingSuggestion, V3SONAOptimizer, } from './SONARouter.helpers.js';
 /**
  * SONARouter routes MCP tool requests through an 8-expert MoE network.
- *
- * The router uses a weighted scoring algorithm to select the optimal expert
- * for each request based on tool-specific weight profiles and real-time
- * expert health/load status.
- *
- * When V3 MoE integration is enabled, it leverages Claude-Flow's neural
- * routing for improved accuracy. Otherwise, it uses the local scoring algorithm.
  */
 export declare class SONARouter {
     private config;
@@ -57,67 +23,17 @@ export declare class SONARouter {
     private v3SONA;
     private initialized;
     private healthCheckInterval;
-    /**
-     * Create a new SONARouter instance.
-     *
-     * @param config - Router configuration
-     */
     constructor(config?: SONARouterConfig);
-    /**
-     * Initialize the router with V3 MoE integration.
-     *
-     * Attempts to load V3 MoERouter and SONAOptimizer.
-     * Falls back to local scoring if V3 is unavailable.
-     */
     initialize(): Promise<void>;
-    /**
-     * Check if router is initialized
-     */
     isInitialized(): boolean;
-    /**
-     * Check if V3 MoE is being used
-     */
     isUsingV3MoE(): boolean;
-    /**
-     * Shutdown the router and cleanup resources
-     */
     shutdown(): Promise<void>;
-    /**
-     * Route a tool request to the optimal expert.
-     *
-     * @param request - Tool request to route
-     * @returns Routing decision with selected expert and confidence
-     */
     route(request: ToolRequest): Promise<RoutingDecision>;
-    /**
-     * Execute a tool request with SONA routing.
-     *
-     * Routes the request, executes via the selected expert, and records outcome.
-     *
-     * @param request - Tool request to execute
-     * @param executor - Function to execute the tool with given expert
-     * @returns Tool response with execution metadata
-     */
     executeWithRouting<T>(request: ToolRequest, executor: (expertId: ExpertId, request: ToolRequest) => Promise<T>): Promise<ToolResponse<T>>;
-    /**
-     * Get current status of all experts
-     */
     getExpertStatus(): ExpertStatus[];
-    /**
-     * Get status of a specific expert
-     */
     getExpert(expertId: ExpertId): ExpertDefinition | undefined;
-    /**
-     * Update expert health status
-     */
     updateExpertHealth(expertId: ExpertId, state: ExpertState, load?: number): void;
-    /**
-     * Get current routing metrics
-     */
     getMetrics(): Partial<SONAMetrics>;
-    /**
-     * Reset metrics
-     */
     resetMetrics(): void;
     private ensureInitialized;
     private createInitialStatus;
@@ -125,13 +41,11 @@ export declare class SONARouter {
     private startHealthChecks;
     private runHealthChecks;
     private generateCacheKey;
-    private hashObject;
     private getEligibleExperts;
     private scoreExperts;
     private calculateScores;
     private selectBestExpert;
     private generateDecisionReason;
-    private generateAlternativeReason;
     private createFallbackDecision;
     private recordOutcome;
 }
@@ -139,16 +53,4 @@ export declare class SONARouter {
  * Create and initialize a SONARouter instance
  */
 export declare function createSONARouter(config?: SONARouterConfig): Promise<SONARouter>;
-/**
- * Check if SONA routing should be used for a request
- */
-export declare function shouldUseSONARouting(tool: ToolType, featureFlags: Record<string, boolean | number>, userTier?: string): boolean;
-/**
- * Check if a routing decision indicates high confidence
- */
-export declare function isHighConfidenceDecision(decision: RoutingDecision): boolean;
-/**
- * Check if a routing decision used fallback
- */
-export declare function usedFallback(decision: RoutingDecision): boolean;
 //# sourceMappingURL=SONARouter.d.ts.map

package/dist/src/routing/SONARouter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SONARouter.d.ts","sourceRoot":"","sources":["../../../src/routing/SONARouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,eAAe,EAEf,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,QAAQ,EAET,MAAM,YAAY,CAAA;AAgNnB;;;;;;;;;GASG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAuE;IACrF,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,mBAAmB,CAA8C;IAEzE;;;;OAIG;gBACS,MAAM,GAAE,gBAAqB;IA2BzC;;;;;OAKG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBjC;;OAEG;IACH,aAAa,IAAI,OAAO;IAIxB;;OAEG;IACH,YAAY,IAAI,OAAO;IAIvB;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAa/B;;;;;OAKG;IACG,KAAK,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;IAqC3D;;;;;;;;OAQG;IACG,kBAAkB,CAAC,CAAC,EACxB,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GACjE,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAkF3B;;OAEG;IACH,eAAe,IAAI,YAAY,EAAE;IAIjC;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,gBAAgB,GAAG,SAAS;IAI3D;;OAEG;IACH,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAe/E;;OAEG;IACH,UAAU,IAAI,OAAO,CAAC,WAAW,CAAC;IAIlC;;OAEG;IACH,YAAY,IAAI,IAAI;IAQpB,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,mBAAmB;YAYb,eAAe;IAwB7B,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,eAAe;IAevB,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,kBAAkB;IA0B1B,OAAO,CAAC,YAAY;IAmBpB,OAAO,CAAC,eAAe;IAgDvB,OAAO,CAAC,gBAAgB;IAiCxB,OAAO,CAAC,sBAAsB;IAc9B,OAAO,CAAC,yBAAyB;IAIjC,OAAO,CAAC,sBAAsB;IAuB9B,OAAO,CAAC,aAAa;CAuBtB;AAMD;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAIrF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,QAAQ,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,EAC9C,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAqBT;AAMD;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAE3E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAE/D"}
+{"version":3,"file":"SONARouter.d.ts","sourceRoot":"","sources":["../../../src/routing/SONARouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,eAAe,EAEf,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,YAAY,EAGb,MAAM,YAAY,CAAA;AASnB,OAAO,EACL,QAAQ,EACR,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,EACxB,YAAY,GACb,MAAM,yBAAyB,CAAA;AAEhC,YAAY,EACV,eAAe,EACf,WAAW,EACX,mBAAmB,EACnB,eAAe,GAChB,MAAM,yBAAyB,CAAA;AAMhC;;GAEG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAuE;IACrF,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,mBAAmB,CAA8C;gBAE7D,MAAM,GAAE,gBAAqB;IAsBnC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAcjC,aAAa,IAAI,OAAO;IAIxB,YAAY,IAAI,OAAO;IAIjB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAazB,KAAK,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;IAgCrD,kBAAkB,CAAC,CAAC,EACxB,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GACjE,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IA4E3B,eAAe,IAAI,YAAY,EAAE;IAIjC,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,gBAAgB,GAAG,SAAS;IAI3D,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAa/E,UAAU,IAAI,OAAO,CAAC,WAAW,CAAC;IAIlC,YAAY,IAAI,IAAI;IAQpB,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,mBAAmB;YAYb,eAAe;IAqB7B,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,kBAAkB;IAgB1B,OAAO,CAAC,YAAY;IAiBpB,OAAO,CAAC,eAAe;IAgCvB,OAAO,CAAC,gBAAgB;IAgCxB,OAAO,CAAC,sBAAsB;IAa9B,OAAO,CAAC,sBAAsB;IAuB9B,OAAO,CAAC,aAAa;CAmBtB;AAMD;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAIrF"}

package/dist/src/routing/SONARouter.helpers.d.ts

@@ -0,0 +1,112 @@
+/**
+ * SONARouter Helper Classes and Functions
+ * @module @skillsmith/core/routing/SONARouter.helpers
+ */
+import type { ExpertId, RoutingDecision, SONAMetrics, ToolType } from './types.js';
+/**
+ * V3 MoERouter result type
+ */
+export interface V3RoutingResult {
+    experts: Array<{
+        name: string;
+        index: number;
+        weight: number;
+        score: number;
+    }>;
+    allScores: number[];
+    loadBalanceLoss: number;
+    entropy: number;
+}
+/**
+ * V3 MoERouter interface
+ */
+export interface V3MoERouter {
+    initialize(): Promise<void>;
+    route(embedding: Float32Array | number[]): V3RoutingResult;
+    updateExpertWeights(expert: string | number, reward: number): void;
+    getStats(): Record<string, number | string>;
+}
+/**
+ * V3 SONAOptimizer suggestion
+ */
+export interface V3RoutingSuggestion {
+    agent: string;
+    confidence: number;
+    usedQLearning: boolean;
+    source: 'sona-pattern' | 'q-learning' | 'keyword-match' | 'default';
+    alternatives: Array<{
+        agent: string;
+        score: number;
+    }>;
+    matchedKeywords?: string[];
+}
+/**
+ * V3 SONAOptimizer interface
+ */
+export interface V3SONAOptimizer {
+    initialize(): Promise<{
+        success: boolean;
+        patternsLoaded: number;
+    }>;
+    getRoutingSuggestion(task: string): V3RoutingSuggestion;
+    processTrajectoryOutcome(outcome: {
+        trajectoryId: string;
+        task: string;
+        agent: string;
+        success: boolean;
+    }): {
+        learned: boolean;
+        patternKey: string;
+        confidence: number;
+    };
+    getStats(): any;
+}
+/**
+ * Simple LRU cache for routing decisions
+ */
+export declare class LRUCache<K, V> {
+    private cache;
+    private readonly maxSize;
+    private readonly ttlMs;
+    constructor(maxSize: number, ttlMs: number);
+    get(key: K): V | null;
+    set(key: K, value: V): void;
+    clear(): void;
+    get size(): number;
+}
+/**
+ * Simple metrics collector for SONA routing
+ */
+export declare class MetricsCollector {
+    private totalRequests;
+    private requestsByTool;
+    private requestsByExpert;
+    private cacheHits;
+    private cacheMisses;
+    private totalRoutingTimeMs;
+    private totalExecutionTimeMs;
+    private errorCount;
+    private errorsByType;
+    recordRouting(tool: ToolType, expertId: ExpertId, routingTimeMs: number, cacheHit: boolean): void;
+    recordExecution(executionTimeMs: number): void;
+    recordError(errorType: string): void;
+    getMetrics(): Partial<SONAMetrics>;
+    reset(): void;
+}
+/**
+ * Check if SONA routing should be used for a request
+ */
+export declare function shouldUseSONARouting(tool: ToolType, featureFlags: Record<string, boolean | number>, userTier?: string): boolean;
+/**
+ * Check if a routing decision indicates high confidence
+ */
+export declare function isHighConfidenceDecision(decision: RoutingDecision): boolean;
+/**
+ * Check if a routing decision used fallback
+ */
+export declare function usedFallback(decision: RoutingDecision): boolean;
+/**
+ * Generate a simple hash from an object (for cache keys)
+ */
+export declare function hashObject(obj: Record<string, unknown>): string;
+//# sourceMappingURL=SONARouter.helpers.d.ts.map

package/dist/src/routing/SONARouter.helpers.d.ts.map

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

package/dist/src/routing/SONARouter.helpers.js

@@ -0,0 +1,184 @@
+/**
+ * SONARouter Helper Classes and Functions
+ * @module @skillsmith/core/routing/SONARouter.helpers
+ */
+// ============================================================================
+// LRU Cache Implementation
+// ============================================================================
+/**
+ * Simple LRU cache for routing decisions
+ */
+export class LRUCache {
+    cache;
+    maxSize;
+    ttlMs;
+    constructor(maxSize, ttlMs) {
+        this.cache = new Map();
+        this.maxSize = maxSize;
+        this.ttlMs = ttlMs;
+    }
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return null;
+        // Check TTL
+        if (Date.now() - entry.timestamp > this.ttlMs) {
+            this.cache.delete(key);
+            return null;
+        }
+        // Move to end (most recently used)
+        this.cache.delete(key);
+        this.cache.set(key, entry);
+        return entry.value;
+    }
+    set(key, value) {
+        // Remove oldest if at capacity
+        if (this.cache.size >= this.maxSize) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey !== undefined) {
+                this.cache.delete(firstKey);
+            }
+        }
+        this.cache.set(key, { value, timestamp: Date.now() });
+    }
+    clear() {
+        this.cache.clear();
+    }
+    get size() {
+        return this.cache.size;
+    }
+}
+// ============================================================================
+// Metrics Collector
+// ============================================================================
+/**
+ * Simple metrics collector for SONA routing
+ */
+export class MetricsCollector {
+    totalRequests = 0;
+    requestsByTool = {};
+    requestsByExpert = {};
+    cacheHits = 0;
+    cacheMisses = 0;
+    totalRoutingTimeMs = 0;
+    totalExecutionTimeMs = 0;
+    errorCount = 0;
+    errorsByType = {};
+    recordRouting(tool, expertId, routingTimeMs, cacheHit) {
+        this.totalRequests++;
+        this.requestsByTool[tool] = (this.requestsByTool[tool] || 0) + 1;
+        this.requestsByExpert[expertId] = (this.requestsByExpert[expertId] || 0) + 1;
+        this.totalRoutingTimeMs += routingTimeMs;
+        if (cacheHit) {
+            this.cacheHits++;
+        }
+        else {
+            this.cacheMisses++;
+        }
+    }
+    recordExecution(executionTimeMs) {
+        this.totalExecutionTimeMs += executionTimeMs;
+    }
+    recordError(errorType) {
+        this.errorCount++;
+        this.errorsByType[errorType] = (this.errorsByType[errorType] || 0) + 1;
+    }
+    getMetrics() {
+        const totalCache = this.cacheHits + this.cacheMisses;
+        const avgRoutingMs = this.totalRequests > 0 ? this.totalRoutingTimeMs / this.totalRequests : 0;
+        const avgExecutionMs = this.totalRequests > 0 ? this.totalExecutionTimeMs / this.totalRequests : 0;
+        return {
+            totalRequests: this.totalRequests,
+            requestsByTool: this.requestsByTool,
+            requestsByExpert: this.requestsByExpert,
+            cache: {
+                hits: this.cacheHits,
+                misses: this.cacheMisses,
+                hitRate: totalCache > 0 ? this.cacheHits / totalCache : 0,
+            },
+            errors: {
+                total: this.errorCount,
+                byType: this.errorsByType,
+                byExpert: {},
+            },
+            speedImprovement: {
+                baselineMs: 100, // Baseline without SONA
+                currentMs: avgRoutingMs + avgExecutionMs,
+                improvementRatio: avgRoutingMs + avgExecutionMs > 0 ? 100 / (avgRoutingMs + avgExecutionMs) : 1,
+            },
+        };
+    }
+    reset() {
+        this.totalRequests = 0;
+        this.requestsByTool = {};
+        this.requestsByExpert = {};
+        this.cacheHits = 0;
+        this.cacheMisses = 0;
+        this.totalRoutingTimeMs = 0;
+        this.totalExecutionTimeMs = 0;
+        this.errorCount = 0;
+        this.errorsByType = {};
+    }
+}
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Check if SONA routing should be used for a request
+ */
+export function shouldUseSONARouting(tool, featureFlags, userTier) {
+    // Master switch
+    if (!featureFlags['sona.enabled']) {
+        return false;
+    }
+    // Tool-specific flag
+    const toolFlag = `sona.tools.${tool}`;
+    if (!featureFlags[toolFlag]) {
+        return false;
+    }
+    // Tier check
+    if (userTier) {
+        const tierFlag = `sona.tiers.${userTier}`;
+        if (!featureFlags[tierFlag]) {
+            return false;
+        }
+    }
+    return true;
+}
+// ============================================================================
+// Type Guards
+// ============================================================================
+/**
+ * Check if a routing decision indicates high confidence
+ */
+export function isHighConfidenceDecision(decision) {
+    return decision.confidence >= 0.8;
+}
+/**
+ * Check if a routing decision used fallback
+ */
+export function usedFallback(decision) {
+    return decision.expertId === 'direct-fallback';
+}
+// ============================================================================
+// Hash Utility
+// ============================================================================
+/**
+ * Generate a simple hash from an object (for cache keys)
+ */
+export function hashObject(obj) {
+    const str = JSON.stringify(obj, Object.keys(obj).sort());
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash = hash & hash;
+    }
+    return hash.toString(36);
+}
+// ============================================================================
+// Factory Helper (Stub for backwards compat - actual implementation in SONARouter.ts)
+// ============================================================================
+// Note: createSONARouter is now exported directly from SONARouter.ts to avoid
+// circular dependency. This re-export is handled in the main file.
+//# sourceMappingURL=SONARouter.helpers.js.map

package/dist/src/routing/SONARouter.helpers.js.map

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