@agentic-qe/v3 3.0.0-alpha.10

package/dist/neural-optimizer/value-network.js

@@ -0,0 +1,278 @@
+/**
+ * Agentic QE v3 - Value Network for Neural Topology Optimizer
+ * ADR-034: RL-based swarm topology optimization
+ *
+ * Implements a neural network for estimating state values using:
+ * - Xavier/He initialization for stable gradients
+ * - ReLU activation for hidden layer
+ * - Backpropagation with TD error
+ * - Optional target network for stability
+ */
+// ============================================================================
+// Value Network Implementation
+// ============================================================================
+/**
+ * Neural network for estimating state values
+ *
+ * Architecture: Input -> Hidden (ReLU) -> Output
+ *
+ * Uses TD learning to update weights based on temporal difference errors.
+ */
+export class ValueNetwork {
+    /** Hidden layer weights [hiddenSize][inputSize] */
+    wHidden;
+    /** Hidden layer biases [hiddenSize] */
+    bHidden;
+    /** Output layer weights [hiddenSize] */
+    wOutput;
+    /** Output layer bias */
+    bOutput;
+    /** Last computed value (for debugging) */
+    lastEstimate = 0;
+    /** Input dimension */
+    inputSize;
+    /** Hidden dimension */
+    hiddenSize;
+    /** Gradient clipping threshold */
+    gradientClip = 1.0;
+    constructor(inputSize, hiddenSize) {
+        this.inputSize = inputSize;
+        this.hiddenSize = hiddenSize;
+        // Xavier/He initialization for weights
+        // For ReLU activation, use He initialization: sqrt(2/n_in)
+        const hiddenScale = Math.sqrt(2 / inputSize);
+        const outputScale = Math.sqrt(2 / hiddenSize);
+        // Initialize hidden layer weights
+        this.wHidden = Array(hiddenSize)
+            .fill(null)
+            .map(() => Array(inputSize)
+            .fill(null)
+            .map(() => this.randn() * hiddenScale));
+        // Initialize hidden layer biases to small positive values (for ReLU)
+        this.bHidden = Array(hiddenSize).fill(0.01);
+        // Initialize output layer weights
+        this.wOutput = Array(hiddenSize)
+            .fill(null)
+            .map(() => this.randn() * outputScale);
+        // Initialize output bias to zero
+        this.bOutput = 0;
+    }
+    /**
+     * Generate random number from standard normal distribution
+     * Using Box-Muller transform
+     */
+    randn() {
+        const u1 = Math.random();
+        const u2 = Math.random();
+        return Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+    }
+    /**
+     * Clip value to prevent gradient explosion
+     */
+    clip(value, threshold = this.gradientClip) {
+        return Math.max(-threshold, Math.min(threshold, value));
+    }
+    /**
+     * ReLU activation function
+     */
+    relu(x) {
+        return Math.max(0, x);
+    }
+    /**
+     * ReLU derivative
+     */
+    reluDerivative(x) {
+        return x > 0 ? 1 : 0;
+    }
+    /**
+     * Forward pass to estimate value of a state
+     *
+     * @param state - State vector (length should match inputSize)
+     * @returns Estimated value
+     */
+    estimate(state) {
+        // Validate input
+        if (state.length !== this.inputSize) {
+            // Pad or truncate to match expected size
+            const paddedState = new Array(this.inputSize).fill(0);
+            for (let i = 0; i < Math.min(state.length, this.inputSize); i++) {
+                paddedState[i] = state[i];
+            }
+            state = paddedState;
+        }
+        // Hidden layer: h = ReLU(W_h * x + b_h)
+        const hidden = new Array(this.hiddenSize);
+        for (let j = 0; j < this.hiddenSize; j++) {
+            let sum = this.bHidden[j];
+            for (let i = 0; i < this.inputSize; i++) {
+                sum += this.wHidden[j][i] * state[i];
+            }
+            hidden[j] = this.relu(sum);
+        }
+        // Output layer: v = W_o * h + b_o
+        let output = this.bOutput;
+        for (let j = 0; j < this.hiddenSize; j++) {
+            output += this.wOutput[j] * hidden[j];
+        }
+        this.lastEstimate = output;
+        return output;
+    }
+    /**
+     * Update weights using TD error via backpropagation
+     *
+     * Uses semi-gradient TD(0) update:
+     * w <- w + alpha * tdError * gradient
+     *
+     * @param state - State that was evaluated
+     * @param tdError - Temporal difference error (reward + gamma * V(s') - V(s))
+     * @param lr - Learning rate
+     */
+    update(state, tdError, lr) {
+        // Validate and pad state
+        if (state.length !== this.inputSize) {
+            const paddedState = new Array(this.inputSize).fill(0);
+            for (let i = 0; i < Math.min(state.length, this.inputSize); i++) {
+                paddedState[i] = state[i];
+            }
+            state = paddedState;
+        }
+        // Forward pass to compute activations (needed for backprop)
+        const hiddenPre = new Array(this.hiddenSize); // Pre-activation values
+        const hiddenPost = new Array(this.hiddenSize); // Post-activation values
+        for (let j = 0; j < this.hiddenSize; j++) {
+            let sum = this.bHidden[j];
+            for (let i = 0; i < this.inputSize; i++) {
+                sum += this.wHidden[j][i] * state[i];
+            }
+            hiddenPre[j] = sum;
+            hiddenPost[j] = this.relu(sum);
+        }
+        // Clip TD error to prevent explosion
+        const clippedTdError = this.clip(tdError, 10.0);
+        // Backward pass: compute gradients and update weights
+        // Output layer gradient: d(loss)/d(w_o) = tdError * h
+        for (let j = 0; j < this.hiddenSize; j++) {
+            const gradient = clippedTdError * hiddenPost[j];
+            this.wOutput[j] += lr * this.clip(gradient);
+        }
+        this.bOutput += lr * this.clip(clippedTdError);
+        // Hidden layer gradient: d(loss)/d(w_h) = tdError * w_o * relu'(pre) * x
+        for (let j = 0; j < this.hiddenSize; j++) {
+            const reluGrad = this.reluDerivative(hiddenPre[j]);
+            const delta = clippedTdError * this.wOutput[j] * reluGrad;
+            for (let i = 0; i < this.inputSize; i++) {
+                const gradient = delta * state[i];
+                this.wHidden[j][i] += lr * this.clip(gradient);
+            }
+            this.bHidden[j] += lr * this.clip(delta);
+        }
+    }
+    /**
+     * Copy weights from another network (for target network updates)
+     */
+    copyFrom(other) {
+        const weights = other.export();
+        this.import(weights);
+    }
+    /**
+     * Soft update from another network (Polyak averaging)
+     *
+     * w <- tau * w_other + (1 - tau) * w
+     */
+    softUpdate(other, tau = 0.01) {
+        const otherWeights = other.export();
+        // Update hidden weights
+        for (let j = 0; j < this.hiddenSize; j++) {
+            for (let i = 0; i < this.inputSize; i++) {
+                this.wHidden[j][i] =
+                    tau * otherWeights.wHidden[j][i] + (1 - tau) * this.wHidden[j][i];
+            }
+            this.bHidden[j] =
+                tau * otherWeights.bHidden[j] + (1 - tau) * this.bHidden[j];
+        }
+        // Update output weights
+        for (let j = 0; j < this.hiddenSize; j++) {
+            this.wOutput[j] =
+                tau * otherWeights.wOutput[j] + (1 - tau) * this.wOutput[j];
+        }
+        this.bOutput = tau * otherWeights.bOutput + (1 - tau) * this.bOutput;
+    }
+    /**
+     * Export weights for serialization
+     */
+    export() {
+        return {
+            wHidden: this.wHidden.map((row) => [...row]),
+            bHidden: [...this.bHidden],
+            wOutput: [...this.wOutput],
+            bOutput: this.bOutput,
+        };
+    }
+    /**
+     * Import weights from serialized data
+     */
+    import(weights) {
+        // Validate dimensions
+        if (weights.wHidden.length !== this.hiddenSize ||
+            weights.wHidden[0].length !== this.inputSize) {
+            throw new Error(`Weight dimension mismatch: expected [${this.hiddenSize}][${this.inputSize}], ` +
+                `got [${weights.wHidden.length}][${weights.wHidden[0]?.length}]`);
+        }
+        this.wHidden = weights.wHidden.map((row) => [...row]);
+        this.bHidden = [...weights.bHidden];
+        this.wOutput = [...weights.wOutput];
+        this.bOutput = weights.bOutput;
+    }
+    /**
+     * Get last computed estimate (for debugging)
+     */
+    getLastEstimate() {
+        return this.lastEstimate;
+    }
+    /**
+     * Get network dimensions
+     */
+    getDimensions() {
+        return {
+            inputSize: this.inputSize,
+            hiddenSize: this.hiddenSize,
+        };
+    }
+    /**
+     * Calculate L2 norm of all weights (for regularization/monitoring)
+     */
+    getWeightNorm() {
+        let sum = 0;
+        for (let j = 0; j < this.hiddenSize; j++) {
+            for (let i = 0; i < this.inputSize; i++) {
+                sum += this.wHidden[j][i] ** 2;
+            }
+            sum += this.bHidden[j] ** 2;
+        }
+        for (let j = 0; j < this.hiddenSize; j++) {
+            sum += this.wOutput[j] ** 2;
+        }
+        sum += this.bOutput ** 2;
+        return Math.sqrt(sum);
+    }
+}
+// ============================================================================
+// Factory Functions
+// ============================================================================
+/**
+ * Create a new value network
+ */
+export function createValueNetwork(inputSize, hiddenSize) {
+    return new ValueNetwork(inputSize, hiddenSize);
+}
+/**
+ * Create a value network from exported weights
+ */
+export function createValueNetworkFromWeights(weights) {
+    const inputSize = weights.wHidden[0]?.length || 0;
+    const hiddenSize = weights.wHidden.length;
+    const network = new ValueNetwork(inputSize, hiddenSize);
+    network.import(weights);
+    return network;
+}
+//# sourceMappingURL=value-network.js.map

package/dist/neural-optimizer/value-network.js.map

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

package/dist/optimization/auto-tuner.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Auto-Tuner Core Implementation
+ * ADR-024: Self-Optimization Engine
+ *
+ * Main orchestrator for automatic parameter tuning.
+ */
+import type { TunableParameter, TuningConfig, EvaluationResult, TuningCycleResult, ParameterSuggestion, AutoTunerState, AutoTunerStats, ParameterApplicator, ParameterApplicatorRegistry } from './types.js';
+import { MetricCollectorRegistry } from './metric-collectors.js';
+import { TuningAlgorithm } from './tuning-algorithm.js';
+/**
+ * Events emitted by the auto-tuner
+ */
+export type AutoTunerEvent = {
+    type: 'cycle-started';
+    cycleId: string;
+} | {
+    type: 'cycle-completed';
+    result: TuningCycleResult;
+} | {
+    type: 'parameter-changed';
+    parameter: string;
+    oldValue: number | string;
+    newValue: number | string;
+} | {
+    type: 'suggestion-generated';
+    suggestions: ParameterSuggestion[];
+} | {
+    type: 'error';
+    error: Error;
+};
+export type AutoTunerEventHandler = (event: AutoTunerEvent) => void;
+/**
+ * Default implementation of ParameterApplicatorRegistry
+ * Manages applicators that bridge tuning suggestions to real system changes
+ */
+export declare class DefaultParameterApplicatorRegistry implements ParameterApplicatorRegistry {
+    private applicators;
+    register(applicator: ParameterApplicator): void;
+    get(parameterName: string): ParameterApplicator | undefined;
+    getAll(): ParameterApplicator[];
+    applyConfiguration(config: Record<string, number | string>): Promise<void>;
+}
+/**
+ * Create a default (empty) parameter applicator registry
+ * Users should register their own applicators for real system integration
+ */
+export declare function createParameterApplicatorRegistry(): ParameterApplicatorRegistry;
+/**
+ * AQE Auto-Tuner
+ *
+ * Automatically tunes system parameters based on performance metrics.
+ * Uses gradient-free optimization to find optimal configurations.
+ */
+export declare class AQEAutoTuner {
+    private parameters;
+    private config;
+    private collectorRegistry;
+    private applicatorRegistry;
+    private algorithm;
+    private state;
+    private evaluationHistory;
+    private eventHandlers;
+    private tuningTimer?;
+    private collectionTimer?;
+    constructor(parameters?: TunableParameter[], config?: Partial<TuningConfig> & {
+        evaluationPeriodMs?: number;
+    }, collectorRegistry?: MetricCollectorRegistry, algorithm?: TuningAlgorithm, applicatorRegistry?: ParameterApplicatorRegistry);
+    /**
+     * Register a parameter applicator for real system integration
+     */
+    registerApplicator(applicator: ParameterApplicator): void;
+    /**
+     * Get the applicator registry
+     */
+    getApplicatorRegistry(): ParameterApplicatorRegistry;
+    /**
+     * Start the auto-tuner
+     */
+    start(): void;
+    /**
+     * Stop the auto-tuner
+     */
+    stop(): void;
+    /**
+     * Check if the tuner is running
+     */
+    isRunning(): boolean;
+    /**
+     * Collect current metrics
+     */
+    collectMetrics(): Promise<void>;
+    /**
+     * Record a search latency metric
+     */
+    recordSearchLatency(latencyMs: number): void;
+    /**
+     * Record a routing outcome (properly handles the two-boolean interface)
+     */
+    recordRoutingOutcome(followedRecommendation: boolean, wasSuccessful: boolean): void;
+    /**
+     * Record a pattern quality score
+     */
+    recordPatternQuality(score: number): void;
+    /**
+     * Record a test maintainability score
+     */
+    recordTestMaintainability(score: number): void;
+    /**
+     * Generic metric recording (for numeric values only)
+     * @deprecated Use specific record methods for type safety
+     */
+    recordMetric(metricName: string, value: number): void;
+    /**
+     * Run a single tuning cycle
+     */
+    runTuningCycle(): Promise<TuningCycleResult>;
+    /**
+     * Run a single evaluation by actually applying a configuration
+     * and measuring the resulting metrics
+     */
+    private runEvaluation;
+    /**
+     * Sleep utility for evaluation period
+     */
+    private sleep;
+    /**
+     * Apply the best configuration found
+     */
+    private applyBestConfiguration;
+    /**
+     * Create a skipped cycle result
+     */
+    private createSkippedCycleResult;
+    /**
+     * Get current parameter values
+     */
+    getCurrentParameterValues(): Record<string, number | string>;
+    /**
+     * Get a specific parameter
+     */
+    getParameter(name: string): TunableParameter | undefined;
+    /**
+     * Update a parameter value manually
+     */
+    setParameter(name: string, value: number | string): boolean;
+    /**
+     * Add a new tunable parameter
+     */
+    addParameter(param: TunableParameter): void;
+    /**
+     * Remove a tunable parameter
+     */
+    removeParameter(name: string): boolean;
+    /**
+     * Enable or disable a parameter for tuning
+     */
+    setParameterEnabled(name: string, enabled: boolean): boolean;
+    /**
+     * Get current state
+     */
+    getState(): AutoTunerState;
+    /**
+     * Get statistics
+     */
+    getStats(): AutoTunerStats;
+    /**
+     * Get evaluation history
+     */
+    getEvaluationHistory(): EvaluationResult[];
+    /**
+     * Get parameter history
+     */
+    getParameterHistory(): AutoTunerState['parameterHistory'];
+    /**
+     * Subscribe to events
+     */
+    on(handler: AutoTunerEventHandler): () => void;
+    /**
+     * Emit an event
+     */
+    private emit;
+    /**
+     * Export state for persistence
+     */
+    exportState(): {
+        parameters: TunableParameter[];
+        evaluationHistory: EvaluationResult[];
+        parameterHistory: AutoTunerState['parameterHistory'];
+    };
+    /**
+     * Import state from persistence
+     */
+    importState(data: {
+        parameters?: TunableParameter[];
+        evaluationHistory?: EvaluationResult[];
+        parameterHistory?: AutoTunerState['parameterHistory'];
+    }): void;
+    /**
+     * Clear all history
+     */
+    clearHistory(): void;
+}
+/**
+ * Create a new AQE auto-tuner
+ */
+export declare function createAutoTuner(parameters?: TunableParameter[], config?: Partial<TuningConfig>): AQEAutoTuner;
+//# sourceMappingURL=auto-tuner.d.ts.map

package/dist/optimization/auto-tuner.d.ts.map

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