@mxf-dev/core 1.0.0

package/dist/services/UtilityScorerService.js

@@ -0,0 +1,343 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * UtilityScorerService
+ *
+ * Two-phase retrieval scoring service for the Memory Utility Learning System (MULS).
+ * Combines similarity scores with Q-values using a configurable lambda parameter.
+ *
+ * Key Formula: score = (1-λ) × sim_normalized + λ × Q_normalized
+ *
+ * Phase-Specific Lambda Rationale:
+ * - OBSERVATION (0.2): Prioritize semantic accuracy for gathering context
+ * - REASONING (0.5): Balance explore/exploit for analysis
+ * - PLANNING (0.7): Exploit proven patterns for strategy
+ * - ACTION (0.3): Stay grounded for tool execution
+ * - REFLECTION (0.6): Favor memories that led to good assessments
+ *
+ * Feature flag: MEMORY_UTILITY_LEARNING_ENABLED
+ */
+import { Logger } from '../utils/Logger.js';
+import { QValueManager } from './QValueManager.js';
+import { DEFAULT_PHASE_LAMBDAS, DEFAULT_MEMORY_UTILITY_CONFIG, getMulsConfigFromEnv } from '../types/MemoryUtilityTypes.js';
+/**
+ * UtilityScorerService - Singleton service for composite memory scoring
+ */
+export class UtilityScorerService {
+    static instance;
+    logger;
+    qValueManager;
+    config;
+    enabled = false;
+    // Lambda overrides for different scopes
+    globalLambda;
+    phaseLambdas;
+    constructor() {
+        this.logger = new Logger('info', 'UtilityScorerService');
+        this.qValueManager = QValueManager.getInstance();
+        this.config = {
+            ...DEFAULT_MEMORY_UTILITY_CONFIG,
+            ...getMulsConfigFromEnv()
+        };
+        this.globalLambda = this.config.lambda;
+        this.phaseLambdas = { ...DEFAULT_PHASE_LAMBDAS, ...this.config.phaseLambdas };
+    }
+    /**
+     * Get the singleton instance
+     */
+    static getInstance() {
+        if (!UtilityScorerService.instance) {
+            UtilityScorerService.instance = new UtilityScorerService();
+        }
+        return UtilityScorerService.instance;
+    }
+    /**
+     * Initialize the UtilityScorerService with configuration
+     */
+    initialize(config) {
+        if (config) {
+            this.config = { ...this.config, ...config };
+            this.globalLambda = this.config.lambda;
+            if (config.phaseLambdas) {
+                this.phaseLambdas = { ...this.phaseLambdas, ...config.phaseLambdas };
+            }
+        }
+        this.enabled = this.config.enabled;
+        if (this.enabled) {
+            this.logger.info('[UtilityScorerService] Initialized with MULS enabled');
+            this.logger.info(`[UtilityScorerService] Global lambda=${this.globalLambda}`);
+            this.logger.info(`[UtilityScorerService] Phase lambdas: ${JSON.stringify(this.phaseLambdas)}`);
+        }
+        else {
+            this.logger.info('[UtilityScorerService] MULS is disabled - pure similarity scoring');
+        }
+    }
+    /**
+     * Check if MULS is enabled
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Score memories using composite formula
+     *
+     * @param query The search query (for logging/tracking)
+     * @param candidates Memory candidates with similarity and Q-value scores
+     * @param options Scoring options
+     * @returns Scored memories sorted by final score descending
+     */
+    scoreMemories(query, candidates, options) {
+        const startTime = Date.now();
+        // If MULS is disabled, return pure similarity ranking
+        if (!this.enabled) {
+            return this.pureSimilarityScoring(candidates, startTime);
+        }
+        const opts = this.mergeOptions(options);
+        const lambda = opts.lambda ?? this.globalLambda;
+        // Step 1: Normalize similarity scores (min-max within candidate pool)
+        const normalizedCandidates = this.normalizeCandidates(candidates, opts.normalizationMethod ?? 'z-score');
+        // Step 2: Apply composite scoring formula
+        const scoredMemories = normalizedCandidates.map(candidate => {
+            const finalScore = (1 - lambda) * candidate.normalizedSimilarity + lambda * candidate.normalizedQValue;
+            const scored = {
+                memoryId: candidate.memoryId,
+                finalScore,
+                content: candidate.content,
+                metadata: candidate.metadata
+            };
+            if (opts.includeBreakdown) {
+                scored.breakdown = {
+                    normalizedSimilarity: candidate.normalizedSimilarity,
+                    normalizedQValue: candidate.normalizedQValue,
+                    lambda,
+                    rawSimilarity: candidate.rawSimilarity,
+                    rawQValue: candidate.rawQValue
+                };
+            }
+            return scored;
+        });
+        // Step 3: Sort by final score descending
+        scoredMemories.sort((a, b) => b.finalScore - a.finalScore);
+        // Step 4: Limit results
+        const maxResults = opts.maxResults ?? this.config.maxResults;
+        const limitedMemories = scoredMemories.slice(0, maxResults);
+        const scoringTimeMs = Date.now() - startTime;
+        this.logger.debug(`[UtilityScorerService] Scored ${candidates.length} candidates in ${scoringTimeMs}ms (lambda=${lambda})`);
+        return {
+            memories: limitedMemories,
+            stats: {
+                candidatesConsidered: candidates.length,
+                resultsReturned: limitedMemories.length,
+                lambdaUsed: lambda,
+                scoringTimeMs
+            }
+        };
+    }
+    /**
+     * Score memories for a specific ORPAR phase
+     *
+     * @param query The search query
+     * @param candidates Memory candidates
+     * @param phase The ORPAR phase for phase-specific lambda
+     * @returns Scored memories
+     */
+    scoreForPhase(query, candidates, phase) {
+        const phaseLambda = this.getLambdaForPhase(phase);
+        this.logger.debug(`[UtilityScorerService] Scoring for phase '${phase}' with lambda=${phaseLambda}`);
+        return this.scoreMemories(query, candidates, { lambda: phaseLambda });
+    }
+    /**
+     * Get the lambda value for a specific ORPAR phase
+     */
+    getLambdaForPhase(phase) {
+        return this.phaseLambdas[phase] ?? this.globalLambda;
+    }
+    /**
+     * Set the global lambda value
+     */
+    setLambda(lambda, scope) {
+        if (lambda < 0 || lambda > 1) {
+            throw new Error(`Lambda must be between 0 and 1, got ${lambda}`);
+        }
+        if (!scope || scope === 'global') {
+            this.globalLambda = lambda;
+            this.logger.info(`[UtilityScorerService] Global lambda set to ${lambda}`);
+        }
+        else {
+            this.phaseLambdas[scope] = lambda;
+            this.logger.info(`[UtilityScorerService] Lambda for phase '${scope}' set to ${lambda}`);
+        }
+    }
+    /**
+     * Get the current lambda value
+     */
+    getLambda(scope) {
+        if (!scope || scope === 'global') {
+            return this.globalLambda;
+        }
+        return this.phaseLambdas[scope] ?? this.globalLambda;
+    }
+    /**
+     * Get all phase lambdas
+     */
+    getPhaseLambdas() {
+        return { ...this.phaseLambdas };
+    }
+    /**
+     * Reset lambdas to default values
+     */
+    resetLambdas() {
+        this.globalLambda = DEFAULT_MEMORY_UTILITY_CONFIG.lambda;
+        this.phaseLambdas = { ...DEFAULT_PHASE_LAMBDAS };
+        this.logger.info('[UtilityScorerService] Reset lambdas to default values');
+    }
+    /**
+     * Pure similarity scoring (when MULS is disabled)
+     */
+    pureSimilarityScoring(candidates, startTime) {
+        const scoredMemories = candidates.map(c => ({
+            memoryId: c.memoryId,
+            finalScore: c.similarity,
+            content: c.content,
+            metadata: c.metadata
+        }));
+        scoredMemories.sort((a, b) => b.finalScore - a.finalScore);
+        const limited = scoredMemories.slice(0, this.config.maxResults);
+        return {
+            memories: limited,
+            stats: {
+                candidatesConsidered: candidates.length,
+                resultsReturned: limited.length,
+                lambdaUsed: 0,
+                scoringTimeMs: Date.now() - startTime
+            }
+        };
+    }
+    /**
+     * Normalize candidates for scoring
+     */
+    normalizeCandidates(candidates, method) {
+        if (candidates.length === 0) {
+            return [];
+        }
+        // Extract raw values
+        const similarities = candidates.map(c => c.similarity);
+        const qValues = candidates.map(c => c.qValue);
+        // Normalize
+        const normalizedSims = this.normalizeArray(similarities, method);
+        const normalizedQs = this.normalizeArray(qValues, method);
+        // Build normalized candidates
+        return candidates.map((candidate, i) => ({
+            memoryId: candidate.memoryId,
+            rawSimilarity: candidate.similarity,
+            rawQValue: candidate.qValue,
+            normalizedSimilarity: normalizedSims[i],
+            normalizedQValue: normalizedQs[i],
+            content: candidate.content,
+            metadata: candidate.metadata
+        }));
+    }
+    /**
+     * Normalize an array of values using the specified method
+     */
+    normalizeArray(values, method) {
+        if (values.length === 0) {
+            return [];
+        }
+        switch (method) {
+            case 'z-score':
+                return this.zScoreNormalize(values);
+            case 'min-max':
+                return this.minMaxNormalize(values);
+            case 'softmax':
+                return this.softmaxNormalize(values);
+            default:
+                return this.zScoreNormalize(values);
+        }
+    }
+    /**
+     * Z-score normalization: (x - mean) / stddev
+     */
+    zScoreNormalize(values) {
+        const mean = values.reduce((sum, v) => sum + v, 0) / values.length;
+        const variance = values.reduce((sum, v) => sum + Math.pow(v - mean, 2), 0) / values.length;
+        const stdDev = Math.sqrt(variance);
+        // Handle edge case: all identical values
+        if (stdDev === 0) {
+            return values.map(() => 0);
+        }
+        return values.map(v => (v - mean) / stdDev);
+    }
+    /**
+     * Min-max normalization: (x - min) / (max - min)
+     */
+    minMaxNormalize(values) {
+        const min = Math.min(...values);
+        const max = Math.max(...values);
+        // Handle edge case: all identical values
+        if (max === min) {
+            return values.map(() => 0.5);
+        }
+        return values.map(v => (v - min) / (max - min));
+    }
+    /**
+     * Softmax normalization: exp(x) / sum(exp(x))
+     */
+    softmaxNormalize(values) {
+        const maxVal = Math.max(...values);
+        const expValues = values.map(v => Math.exp(v - maxVal));
+        const sumExp = expValues.reduce((sum, v) => sum + v, 0);
+        return expValues.map(v => v / sumExp);
+    }
+    /**
+     * Merge options with defaults
+     */
+    mergeOptions(options) {
+        return {
+            lambda: options?.lambda ?? this.globalLambda,
+            maxCandidates: options?.maxCandidates ?? this.config.maxCandidates,
+            maxResults: options?.maxResults ?? this.config.maxResults,
+            normalizationMethod: options?.normalizationMethod ?? this.config.normalizationMethod,
+            similarityThreshold: options?.similarityThreshold ?? this.config.similarityThreshold,
+            includeBreakdown: options?.includeBreakdown ?? false
+        };
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Update configuration
+     */
+    updateConfig(updates) {
+        this.config = { ...this.config, ...updates };
+        this.enabled = this.config.enabled;
+        if (updates.lambda !== undefined) {
+            this.globalLambda = updates.lambda;
+        }
+        if (updates.phaseLambdas) {
+            this.phaseLambdas = { ...this.phaseLambdas, ...updates.phaseLambdas };
+        }
+        this.logger.info('[UtilityScorerService] Configuration updated');
+    }
+}
+//# sourceMappingURL=UtilityScorerService.js.map

package/dist/services/UtilityScorerService.js.map

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

package/dist/services/ValidationAnalyticsService.d.ts

@@ -0,0 +1,332 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * ValidationAnalyticsService - Phase 6 Advanced Analytics
+ *
+ * Core analytics functionality for validation system including:
+ * - Real-time metric aggregation
+ * - Trend analysis and forecasting
+ * - A/B testing framework
+ * - ROI calculation engine
+ * - Custom report generation
+ */
+import { EventEmitter } from 'events';
+/**
+ * Analytics time ranges
+ */
+export declare enum TimeRange {
+    HOUR = "hour",
+    DAY = "day",
+    WEEK = "week",
+    MONTH = "month",
+    QUARTER = "quarter"
+}
+/**
+ * Metric aggregation types
+ */
+export declare enum AggregationType {
+    SUM = "sum",
+    AVERAGE = "average",
+    MAX = "max",
+    MIN = "min",
+    COUNT = "count",
+    PERCENTILE = "percentile"
+}
+/**
+ * A/B test configuration
+ */
+export interface ABTestConfig {
+    testId: string;
+    name: string;
+    description: string;
+    startTime: number;
+    endTime?: number;
+    variants: ABTestVariant[];
+    metrics: string[];
+    targetAudience?: {
+        agentTypes?: string[];
+        channelTypes?: string[];
+        toolNames?: string[];
+    };
+    status: 'draft' | 'active' | 'completed' | 'cancelled';
+}
+/**
+ * A/B test variant
+ */
+export interface ABTestVariant {
+    id: string;
+    name: string;
+    config: Record<string, any>;
+    allocation: number;
+}
+/**
+ * Analytics metric
+ */
+export interface AnalyticsMetric {
+    name: string;
+    value: number;
+    timestamp: number;
+    dimensions: Record<string, string>;
+    metadata?: Record<string, any>;
+}
+/**
+ * Trend analysis result
+ */
+export interface TrendAnalysis {
+    metric: string;
+    timeRange: TimeRange;
+    trend: 'increasing' | 'decreasing' | 'stable' | 'volatile';
+    changeRate: number;
+    forecast: {
+        nextPeriod: number;
+        confidence: number;
+        upperBound: number;
+        lowerBound: number;
+    };
+    seasonality?: {
+        detected: boolean;
+        pattern: string;
+        strength: number;
+    };
+}
+/**
+ * ROI calculation result
+ */
+export interface ROICalculation {
+    metric: string;
+    timeRange: TimeRange;
+    investment: {
+        development: number;
+        infrastructure: number;
+        maintenance: number;
+        total: number;
+    };
+    returns: {
+        errorReduction: number;
+        timesSaved: number;
+        productivityGain: number;
+        total: number;
+    };
+    roi: number;
+    paybackPeriod: number;
+    breakEvenDate?: number;
+}
+/**
+ * Custom report configuration
+ */
+export interface CustomReportConfig {
+    reportId: string;
+    name: string;
+    description: string;
+    schedule?: {
+        frequency: 'daily' | 'weekly' | 'monthly';
+        time: string;
+        recipients: string[];
+    };
+    sections: ReportSection[];
+    filters?: Record<string, any>;
+}
+/**
+ * Report section
+ */
+export interface ReportSection {
+    type: 'metrics' | 'charts' | 'table' | 'text';
+    title: string;
+    config: Record<string, any>;
+}
+/**
+ * Validation Analytics Service
+ */
+export declare class ValidationAnalyticsService extends EventEmitter {
+    private readonly logger;
+    private readonly validationPerformanceService;
+    private readonly patternLearningService;
+    private readonly proactiveValidationService;
+    private readonly autoCorrectionService;
+    private readonly metricsBuffer;
+    private readonly aggregatedMetrics;
+    private readonly activeABTests;
+    private readonly abTestResults;
+    private readonly customReports;
+    private config;
+    private static instance;
+    private constructor();
+    /**
+     * Get singleton instance
+     */
+    static getInstance(): ValidationAnalyticsService;
+    /**
+     * Record a metric
+     */
+    recordMetric(metric: AnalyticsMetric): void;
+    /**
+     * Aggregate validation metrics
+     */
+    aggregateValidationMetrics(timeRange: TimeRange, dimensions?: Record<string, string>): Promise<Record<string, any>>;
+    /**
+     * Analyze trends for a metric
+     */
+    analyzeTrends(metricName: string, timeRange: TimeRange, options?: {
+        smoothing?: boolean;
+        seasonalityDetection?: boolean;
+        forecastPeriods?: number;
+    }): Promise<TrendAnalysis>;
+    /**
+     * Calculate trend direction
+     */
+    private calculateTrend;
+    /**
+     * Calculate volatility
+     */
+    private calculateVolatility;
+    /**
+     * Calculate change rate
+     */
+    private calculateChangeRate;
+    /**
+     * Forecast metric value
+     */
+    private forecastMetric;
+    /**
+     * Detect seasonality
+     */
+    private detectSeasonality;
+    /**
+     * Calculate autocorrelation
+     */
+    private calculateAutocorrelation;
+    /**
+     * Create A/B test
+     */
+    createABTest(config: Omit<ABTestConfig, 'testId' | 'status'>): ABTestConfig;
+    /**
+     * Start A/B test
+     */
+    startABTest(testId: string): void;
+    /**
+     * Record A/B test event
+     */
+    recordABTestEvent(testId: string, variantId: string, eventType: 'impression' | 'conversion' | 'metric', data?: any): void;
+    /**
+     * Get A/B test results
+     */
+    getABTestResults(testId: string): any;
+    /**
+     * Calculate metric averages
+     */
+    private calculateMetricAverages;
+    /**
+     * Calculate statistical significance
+     */
+    private calculateStatisticalSignificance;
+    /**
+     * Calculate ROI
+     */
+    calculateROI(metric: string, timeRange: TimeRange, investmentData?: {
+        development?: number;
+        infrastructure?: number;
+        maintenance?: number;
+    }): Promise<ROICalculation>;
+    /**
+     * Create custom report
+     */
+    createCustomReport(config: Omit<CustomReportConfig, 'reportId'>): CustomReportConfig;
+    /**
+     * Generate custom report
+     */
+    generateCustomReport(reportId: string): Promise<any>;
+    /**
+     * Generate report section
+     */
+    private generateReportSection;
+    /**
+     * Get start time for time range
+     */
+    private getStartTime;
+    /**
+     * Get days in time range
+     */
+    private getDaysInTimeRange;
+    /**
+     * Get historical data for metric
+     */
+    private getHistoricalData;
+    /**
+     * Get pattern metrics
+     */
+    private getPatternMetrics;
+    /**
+     * Get proactive metrics
+     */
+    private getProactiveMetrics;
+    /**
+     * Get correction metrics
+     */
+    private getCorrectionMetrics;
+    /**
+     * Generate chart data
+     */
+    private generateChartData;
+    /**
+     * Generate table data
+     */
+    private generateTableData;
+    /**
+     * Configure variant routing
+     */
+    private configureVariantRouting;
+    /**
+     * Schedule report
+     */
+    private scheduleReport;
+    /**
+     * Setup event listeners
+     */
+    private setupEventListeners;
+    /**
+     * Start aggregation worker
+     */
+    private startAggregationWorker;
+    /**
+     * Perform metric aggregation
+     */
+    private performAggregation;
+    /**
+     * Get configuration
+     */
+    getConfig(): any;
+    /**
+     * Update configuration
+     */
+    updateConfig(newConfig: Partial<typeof this.config>): void;
+    /**
+     * Get active A/B tests
+     */
+    getActiveABTests(): ABTestConfig[];
+    /**
+     * Get custom reports
+     */
+    getCustomReports(): CustomReportConfig[];
+    /**
+     * Clear metrics (for testing)
+     */
+    clearMetrics(): void;
+}
+//# sourceMappingURL=ValidationAnalyticsService.d.ts.map