cognitive-core 0.2.4 → 0.3.1

package/dist/experimental/moe-gate.js

@@ -0,0 +1,240 @@
+/**
+ * MoEGate — Mixture-of-Experts inspired gating for task routing.
+ *
+ * Learns per-domain weight vectors over routing strategies from outcome
+ * feedback. Replaces threshold-based strategy selection with a learned
+ * linear gate:
+ *
+ *   gate(features) = softmax(W · features)
+ *
+ * where W is a weight matrix (one row per strategy), and features are
+ * extracted from the task + memory state.
+ *
+ * Online gradient update:
+ *   w[chosen] += learningRate * reward * features
+ *   w[others] -= learningRate * (1 - reward) * features / (numStrategies - 1)
+ *
+ * Cold start: uniform weights → falls back to existing threshold logic.
+ *
+ * QUARANTINED (core-loop walkback, Pass 2): the gate was never trained in
+ * production — `Router.updateGate()`'s only callers were tests — so the
+ * routing-override branch was permanently dead. Moved here out of the core hot
+ * path; retained for reference / possible future revival. The difficulty signal
+ * it consumed (`computeTaskDifficulty`) is a live router feature and stays in
+ * core at `search/task-difficulty.ts`. See docs/DESIGN-core-loop-walkback.md.
+ */
+import { computeTaskDifficulty } from '../search/task-difficulty.js';
+/**
+ * MoE-inspired gating function over routing strategies
+ */
+export class MoEGate {
+    strategies;
+    featureSize;
+    globalWeights;
+    domainWeights = new Map();
+    updateCount = 0;
+    constructor(strategies, featureSize) {
+        this.strategies = strategies;
+        this.featureSize = featureSize;
+        // Initialize global weights to small random values (near-uniform gate)
+        this.globalWeights = strategies.map(() => Array.from({ length: featureSize }, () => (Math.random() - 0.5) * 0.01));
+    }
+    /**
+     * Compute gate weights for a task given its feature vector.
+     * Returns a map of strategy → probability.
+     */
+    gate(features, domain) {
+        const weights = this.getWeights(domain);
+        const logits = this.computeLogits(weights, features);
+        const probs = this.softmax(logits);
+        const result = new Map();
+        for (let i = 0; i < this.strategies.length; i++) {
+            result.set(this.strategies[i], probs[i]);
+        }
+        return result;
+    }
+    /**
+     * Select the best strategy (argmax of gate output).
+     */
+    selectStrategy(features, domain) {
+        const gateOutput = this.gate(features, domain);
+        let bestStrategy = this.strategies[0];
+        let bestProb = -1;
+        for (const [strategy, prob] of gateOutput) {
+            if (prob > bestProb) {
+                bestProb = prob;
+                bestStrategy = strategy;
+            }
+        }
+        return bestStrategy;
+    }
+    /**
+     * Update weights from outcome feedback (online gradient).
+     *
+     * Positive reward → increase weight for chosen strategy's features.
+     * Negative reward → decrease weight.
+     */
+    update(features, chosenStrategy, reward, learningRate = 0.01, domain) {
+        const chosenIdx = this.strategies.indexOf(chosenStrategy);
+        if (chosenIdx === -1)
+            return;
+        // Update global weights
+        this.updateWeightMatrix(this.globalWeights, features, chosenIdx, reward, learningRate);
+        // Update domain-specific weights if domain provided
+        if (domain) {
+            if (!this.domainWeights.has(domain)) {
+                // Initialize domain weights as copy of global
+                this.domainWeights.set(domain, this.globalWeights.map((row) => [...row]));
+            }
+            const domainW = this.domainWeights.get(domain);
+            this.updateWeightMatrix(domainW, features, chosenIdx, reward, learningRate);
+        }
+        this.updateCount++;
+    }
+    /**
+     * Whether the gate has been trained (has seen any updates).
+     */
+    get isTrained() {
+        return this.updateCount > 0;
+    }
+    /**
+     * Number of updates the gate has seen.
+     */
+    get totalUpdates() {
+        return this.updateCount;
+    }
+    /**
+     * Serialize for persistence.
+     */
+    toJSON() {
+        const domainWeights = {};
+        for (const [domain, weights] of this.domainWeights) {
+            domainWeights[domain] = weights;
+        }
+        return {
+            strategies: this.strategies,
+            featureSize: this.featureSize,
+            globalWeights: this.globalWeights,
+            domainWeights,
+            updateCount: this.updateCount,
+        };
+    }
+    /**
+     * Deserialize from persisted state.
+     */
+    static fromJSON(data) {
+        const gate = new MoEGate(data.strategies, data.featureSize);
+        gate.globalWeights = data.globalWeights;
+        gate.updateCount = data.updateCount;
+        for (const [domain, weights] of Object.entries(data.domainWeights)) {
+            gate.domainWeights.set(domain, weights);
+        }
+        return gate;
+    }
+    // === Internal ===
+    /**
+     * Get the weight matrix for a domain (with fallback to global).
+     */
+    getWeights(domain) {
+        if (domain && this.domainWeights.has(domain)) {
+            return this.domainWeights.get(domain);
+        }
+        return this.globalWeights;
+    }
+    /**
+     * Compute logits = W · features for each strategy.
+     */
+    computeLogits(weights, features) {
+        return weights.map((row) => {
+            let sum = 0;
+            for (let j = 0; j < Math.min(row.length, features.length); j++) {
+                sum += row[j] * features[j];
+            }
+            return sum;
+        });
+    }
+    /**
+     * Softmax with numerical stability (subtract max).
+     */
+    softmax(logits) {
+        const max = Math.max(...logits);
+        const exps = logits.map((l) => Math.exp(l - max));
+        const sum = exps.reduce((a, b) => a + b, 0);
+        return exps.map((e) => e / sum);
+    }
+    /**
+     * Online gradient update on a weight matrix.
+     *
+     * Uses centered reward (reward - 0.5) so that:
+     *   reward=1 → positive update for chosen, negative for others
+     *   reward=0 → negative update for chosen, positive for others
+     */
+    updateWeightMatrix(weights, features, chosenIdx, reward, learningRate) {
+        const numStrategies = this.strategies.length;
+        const centered = reward - 0.5; // range: [-0.5, 0.5]
+        for (let i = 0; i < numStrategies; i++) {
+            for (let j = 0; j < this.featureSize; j++) {
+                if (i === chosenIdx) {
+                    // Positive reward → boost chosen; negative → penalize chosen
+                    weights[i][j] += learningRate * centered * features[j];
+                }
+                else {
+                    // Opposite direction for unchosen strategies
+                    weights[i][j] -= (learningRate * centered * features[j]) / (numStrategies - 1);
+                }
+            }
+        }
+    }
+}
+/**
+ * Extract feature vector from a task and memory context for the MoE gate.
+ *
+ * Features (8 dimensions):
+ * 0: task description length (normalized)
+ * 1: domain familiarity (experience count, normalized)
+ * 2: best experience match score
+ * 3: best playbook match score
+ * 4: best playbook confidence
+ * 5: is bug fix (0/1)
+ * 6: is new feature (0/1)
+ * 7: GENERAL task difficulty score in [0,1] (G6 — replaces the old raw
+ *    word-count proxy with the domain-agnostic structural difficulty signal)
+ *
+ * `tools` (optional) feeds the tool-diversity component of difficulty.
+ */
+export function extractTaskFeatures(taskDescription, memoryContext, experienceCountInDomain = 0, tools = []) {
+    const desc = taskDescription.toLowerCase();
+    const bestExpScore = memoryContext.experiences.length > 0
+        ? Math.max(...memoryContext.experiences.map((e) => e.score))
+        : 0;
+    const bestPlaybookScore = memoryContext.playbooks.length > 0
+        ? Math.max(...memoryContext.playbooks.map((p) => p.score))
+        : 0;
+    const bestPlaybookConfidence = memoryContext.playbooks.length > 0
+        ? Math.max(...memoryContext.playbooks.map((p) => p.playbook.confidence))
+        : 0;
+    const isBugFix = desc.includes('bug') || desc.includes('fix') || desc.includes('error') ? 1 : 0;
+    const isNewFeature = desc.includes('implement') || desc.includes('create') || desc.includes('add') ? 1 : 0;
+    const difficulty = computeTaskDifficulty(taskDescription, tools);
+    return [
+        Math.min(taskDescription.length / 1000, 1), // [0] length, normalized
+        Math.min(experienceCountInDomain / 100, 1), // [1] domain familiarity
+        bestExpScore, // [2] best experience match
+        bestPlaybookScore, // [3] best playbook match
+        bestPlaybookConfidence, // [4] best playbook confidence
+        isBugFix, // [5] bug fix indicator
+        isNewFeature, // [6] new feature indicator
+        difficulty.score, // [7] general difficulty signal
+    ];
+}
+/** Default feature size for the MoE gate */
+export const MOE_FEATURE_SIZE = 8;
+/** Default strategies for the MoE gate */
+export const MOE_STRATEGIES = ['direct', 'adapt', 'explore', 'fallback'];
+/**
+ * Create a MoEGate with default settings
+ */
+export function createMoEGate() {
+    return new MoEGate([...MOE_STRATEGIES], MOE_FEATURE_SIZE);
+}
+//# sourceMappingURL=moe-gate.js.map

package/dist/experimental/moe-gate.js.map

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

package/dist/experimental/reasoning-bank.d.ts

@@ -0,0 +1,130 @@
+/**
+ * ReasoningBank — Pre-clusters successful experiences for faster, more
+ * interpretable retrieval.
+ *
+ * Uses K-means++ on tokenized task descriptions (bag-of-words similarity).
+ * No embedding dependency — works with textSimilarity only.
+ *
+ * Clustering algorithm:
+ * 1. Initialize k centroids using K-means++ (farthest-point initialization)
+ * 2. Assign experiences to nearest centroid by textSimilarity
+ * 3. Recompute centroids (experience with highest avg similarity to members)
+ * 4. Repeat until convergence or maxIterations
+ * 5. Label clusters by top-3 most frequent non-stop tokens
+ */
+import type { Experience } from '../types/index.js';
+import type { SqlitePersistence } from '../persistence/index.js';
+/**
+ * A cluster of similar experiences
+ */
+export interface ExperienceCluster {
+    id: string;
+    /** Auto-generated label from common tokens */
+    label: string;
+    /** Representative taskInput (closest to cluster mean) */
+    centroid: string;
+    /** IDs of experiences in this cluster */
+    experienceIds: string[];
+    /** Aggregate success rate */
+    successRate: number;
+    /** Average access score (from Phase 0) */
+    avgAccessScore: number;
+    /** Domains represented */
+    domains: string[];
+}
+/**
+ * Cluster statistics
+ */
+export interface ClusterStats {
+    clusterId: string;
+    label: string;
+    successRate: number;
+    size: number;
+}
+/**
+ * Configuration for ReasoningBank
+ */
+export interface ReasoningBankConfig {
+    /** Maximum number of clusters (default: 20) */
+    maxClusters?: number;
+    /** Minimum experiences per cluster (default: 3) */
+    minClusterSize?: number;
+    /** Re-cluster after this many new experiences (default: 50) */
+    reclusterInterval?: number;
+    /** Max K-means iterations (default: 10) */
+    maxIterations?: number;
+}
+/**
+ * ReasoningBank — clustered experience retrieval
+ */
+export declare class ReasoningBank {
+    private clusters;
+    private experienceIndex;
+    private experiencesSinceLastCluster;
+    private config;
+    private persistence?;
+    constructor(config?: ReasoningBankConfig, persistence?: SqlitePersistence);
+    /**
+     * Build clusters from a set of experiences.
+     * Filters to successful experiences only.
+     */
+    buildClusters(experiences: Experience[]): void;
+    /**
+     * Find the nearest cluster for a query, then search within it.
+     */
+    findInCluster(query: string, options?: {
+        k?: number;
+        domain?: string;
+    }): Array<{
+        experience: Experience;
+        score: number;
+        clusterId: string;
+    }>;
+    /**
+     * Get all clusters.
+     */
+    getClusters(): ExperienceCluster[];
+    /**
+     * Get cluster-level statistics.
+     */
+    getClusterStats(): ClusterStats[];
+    /**
+     * Check whether re-clustering should be triggered.
+     */
+    shouldRecluster(): boolean;
+    /**
+     * Load persisted clusters. Call after persistence is initialized.
+     */
+    loadPersistedState(): void;
+    /**
+     * Notify that a new experience was added (for recluster tracking).
+     */
+    notifyNewExperience(): void;
+    /**
+     * Get the number of clusters.
+     */
+    get clusterCount(): number;
+    /**
+     * K-means++ clustering on experience taskInputs using textSimilarity.
+     * Returns a map of clusterId → memberIds.
+     */
+    private kMeansPlusPlus;
+    /**
+     * K-means++ initialization: select centroids using farthest-point heuristic.
+     */
+    private initCentroids;
+    /**
+     * Find the centroid of a cluster: the experience with highest average
+     * similarity to all other members.
+     */
+    private findCentroid;
+    /**
+     * Generate a cluster label from the top-3 most frequent non-stop tokens.
+     */
+    private generateLabel;
+}
+/**
+ * Create a ReasoningBank instance
+ */
+export declare function createReasoningBank(config?: ReasoningBankConfig, persistence?: SqlitePersistence): ReasoningBank;
+//# sourceMappingURL=reasoning-bank.d.ts.map

package/dist/experimental/reasoning-bank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoning-bank.d.ts","sourceRoot":"","sources":["../../src/experimental/reasoning-bank.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAGjE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,cAAc,EAAE,MAAM,CAAC;IACvB,0BAA0B;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,2CAA2C;IAC3C,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAuGD;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAA6C;IAC7D,OAAO,CAAC,eAAe,CAAsC;IAC7D,OAAO,CAAC,2BAA2B,CAAK;IACxC,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,WAAW,CAAC,CAAoB;gBAE5B,MAAM,CAAC,EAAE,mBAAmB,EAAE,WAAW,CAAC,EAAE,iBAAiB;IAsBzE;;;OAGG;IACH,aAAa,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,IAAI;IA8D9C;;OAEG;IACH,aAAa,CACX,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACxC,KAAK,CAAC;QAAE,UAAU,EAAE,UAAU,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAqCtE;;OAEG;IACH,WAAW,IAAI,iBAAiB,EAAE;IAIlC;;OAEG;IACH,eAAe,IAAI,YAAY,EAAE;IASjC;;OAEG;IACH,eAAe,IAAI,OAAO;IAI1B;;OAEG;IACH,kBAAkB,IAAI,IAAI;IAa1B;;OAEG;IACH,mBAAmB,IAAI,IAAI;IAI3B;;OAEG;IACH,IAAI,YAAY,IAAI,MAAM,CAEzB;IAID;;;OAGG;IACH,OAAO,CAAC,cAAc;IA2EtB;;OAEG;IACH,OAAO,CAAC,aAAa;IAoCrB;;;OAGG;IACH,OAAO,CAAC,YAAY;IAsBpB;;OAEG;IACH,OAAO,CAAC,aAAa;CAoBtB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,CAAC,EAAE,mBAAmB,EAC5B,WAAW,CAAC,EAAE,iBAAiB,GAC9B,aAAa,CAEf"}