@timmeck/brain-core 2.3.0 → 2.4.0

package/dist/causal/engine.d.ts

@@ -0,0 +1,98 @@
+import type Database from 'better-sqlite3';
+export interface CausalEvent {
+    source: string;
+    type: string;
+    timestamp: number;
+    data?: unknown;
+}
+export interface CausalEdge {
+    id?: number;
+    cause: string;
+    effect: string;
+    strength: number;
+    confidence: number;
+    lag_ms: number;
+    sample_size: number;
+    direction: number;
+}
+export interface CausalPath {
+    chain: string[];
+    totalStrength: number;
+    totalLag: number;
+}
+export interface CausalAnalysis {
+    edges: CausalEdge[];
+    roots: string[];
+    leaves: string[];
+    strongestChain: CausalPath | null;
+}
+export declare function runCausalMigration(db: Database.Database): void;
+/**
+ * Causal Inference Engine: detects cause→effect relationships between events.
+ *
+ * Research approach: Simplified Granger Causality.
+ *
+ * Granger causality asks: "Does knowing that event A happened improve
+ * our ability to predict event B?" If yes, A Granger-causes B.
+ *
+ * Algorithm:
+ * 1. Record all events with timestamps
+ * 2. For each pair of event types (A, B):
+ *    a. Count how often B occurs within a time window after A
+ *    b. Compare this to the baseline rate of B
+ *    c. If B is significantly more likely after A → A causes B
+ * 3. Build a directed graph of causal relationships
+ * 4. Detect causal chains (A → B → C)
+ */
+export declare class CausalGraph {
+    private db;
+    private logger;
+    private maxWindowMs;
+    private minSamples;
+    private significanceThreshold;
+    constructor(db: Database.Database, config?: {
+        maxWindowMs?: number;
+        minSamples?: number;
+        significanceThreshold?: number;
+    });
+    /** Record an event for causal analysis. */
+    recordEvent(source: string, type: string, data?: unknown): void;
+    /**
+     * Run Granger causality analysis on all event pairs.
+     * This is the core research algorithm.
+     */
+    analyze(): CausalEdge[];
+    /**
+     * Test if event type A Granger-causes event type B.
+     *
+     * Algorithm:
+     * 1. Get all timestamps for A and B
+     * 2. For each occurrence of A, check if B occurs within the window after
+     * 3. Calculate: P(B after A) vs P(B in any random window)
+     * 4. If ratio > threshold → A Granger-causes B
+     */
+    private testGrangerCausality;
+    /** Get all detected causal edges (strongest first). */
+    getEdges(minStrength?: number): CausalEdge[];
+    /** Get causes of a specific event type. */
+    getCauses(eventType: string): CausalEdge[];
+    /** Get effects of a specific event type. */
+    getEffects(eventType: string): CausalEdge[];
+    /** Find causal chains (A → B → C). */
+    findChains(maxDepth?: number): CausalPath[];
+    /** Full causal analysis including graph structure. */
+    getAnalysis(): CausalAnalysis;
+    /** Get event type statistics. */
+    getEventStats(): Array<{
+        type: string;
+        count: number;
+        first_seen: number;
+        last_seen: number;
+    }>;
+    private getEventTypes;
+    private getTimeRange;
+    private upsertEdge;
+    private findRoots;
+    private findLeaves;
+    private dfs;
+}

package/dist/causal/engine.js

@@ -0,0 +1,265 @@
+import { getLogger } from '../utils/logger.js';
+// ── Migration ───────────────────────────────────────────
+export function runCausalMigration(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS causal_events (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      source TEXT NOT NULL,
+      type TEXT NOT NULL,
+      timestamp INTEGER NOT NULL,
+      data TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS causal_edges (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      cause TEXT NOT NULL,
+      effect TEXT NOT NULL,
+      strength REAL NOT NULL DEFAULT 0,
+      confidence REAL NOT NULL DEFAULT 0,
+      lag_ms REAL NOT NULL DEFAULT 0,
+      sample_size INTEGER NOT NULL DEFAULT 0,
+      direction REAL NOT NULL DEFAULT 1,
+      updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+      UNIQUE(cause, effect)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_causal_events_type ON causal_events(type);
+    CREATE INDEX IF NOT EXISTS idx_causal_events_timestamp ON causal_events(timestamp);
+    CREATE INDEX IF NOT EXISTS idx_causal_edges_strength ON causal_edges(strength DESC);
+  `);
+}
+// ── Engine ───────────────────────────────────────────────
+/**
+ * Causal Inference Engine: detects cause→effect relationships between events.
+ *
+ * Research approach: Simplified Granger Causality.
+ *
+ * Granger causality asks: "Does knowing that event A happened improve
+ * our ability to predict event B?" If yes, A Granger-causes B.
+ *
+ * Algorithm:
+ * 1. Record all events with timestamps
+ * 2. For each pair of event types (A, B):
+ *    a. Count how often B occurs within a time window after A
+ *    b. Compare this to the baseline rate of B
+ *    c. If B is significantly more likely after A → A causes B
+ * 3. Build a directed graph of causal relationships
+ * 4. Detect causal chains (A → B → C)
+ */
+export class CausalGraph {
+    db;
+    logger = getLogger();
+    maxWindowMs; // max time lag to consider
+    minSamples; // minimum observations for significance
+    significanceThreshold; // minimum ratio to baseline for significance
+    constructor(db, config) {
+        this.db = db;
+        runCausalMigration(db);
+        this.maxWindowMs = config?.maxWindowMs ?? 300_000; // 5 minutes
+        this.minSamples = config?.minSamples ?? 5;
+        this.significanceThreshold = config?.significanceThreshold ?? 1.5; // 50% above baseline
+    }
+    /** Record an event for causal analysis. */
+    recordEvent(source, type, data) {
+        this.db.prepare(`
+      INSERT INTO causal_events (source, type, timestamp, data)
+      VALUES (?, ?, ?, ?)
+    `).run(source, type, Date.now(), data ? JSON.stringify(data) : null);
+    }
+    /**
+     * Run Granger causality analysis on all event pairs.
+     * This is the core research algorithm.
+     */
+    analyze() {
+        const eventTypes = this.getEventTypes();
+        if (eventTypes.length < 2)
+            return [];
+        const edges = [];
+        // For each pair of event types, test for Granger causality
+        for (const cause of eventTypes) {
+            for (const effect of eventTypes) {
+                if (cause === effect)
+                    continue;
+                const edge = this.testGrangerCausality(cause, effect);
+                if (edge) {
+                    this.upsertEdge(edge);
+                    edges.push(edge);
+                }
+            }
+        }
+        this.logger.info(`Causal analysis complete: ${edges.length} causal relationships detected`);
+        return edges;
+    }
+    /**
+     * Test if event type A Granger-causes event type B.
+     *
+     * Algorithm:
+     * 1. Get all timestamps for A and B
+     * 2. For each occurrence of A, check if B occurs within the window after
+     * 3. Calculate: P(B after A) vs P(B in any random window)
+     * 4. If ratio > threshold → A Granger-causes B
+     */
+    testGrangerCausality(causeType, effectType) {
+        const causeEvents = this.db.prepare('SELECT timestamp FROM causal_events WHERE type = ? ORDER BY timestamp').all(causeType);
+        const effectEvents = this.db.prepare('SELECT timestamp FROM causal_events WHERE type = ? ORDER BY timestamp').all(effectType);
+        if (causeEvents.length < this.minSamples || effectEvents.length < this.minSamples) {
+            return null;
+        }
+        // Calculate: how often does effectType occur within maxWindowMs after causeType?
+        let followCount = 0;
+        let totalLag = 0;
+        for (const cause of causeEvents) {
+            // Find the first effect event within the window
+            for (const effect of effectEvents) {
+                const lag = effect.timestamp - cause.timestamp;
+                if (lag > 0 && lag <= this.maxWindowMs) {
+                    followCount++;
+                    totalLag += lag;
+                    break; // only count first occurrence per cause event
+                }
+                if (lag > this.maxWindowMs)
+                    break; // past window, stop looking
+            }
+        }
+        if (followCount < this.minSamples)
+            return null;
+        // P(effect follows cause) = followCount / causeEvents.length
+        const pFollows = followCount / causeEvents.length;
+        // Baseline: P(effect in any random window of same size)
+        // Estimate: total effect events / total time * window size
+        const timeRange = this.getTimeRange();
+        if (timeRange <= 0)
+            return null;
+        const baselineRate = (effectEvents.length / timeRange) * this.maxWindowMs;
+        const pBaseline = Math.min(1, baselineRate);
+        // Significance: is the conditional probability significantly higher than baseline?
+        if (pBaseline <= 0)
+            return null;
+        const ratio = pFollows / pBaseline;
+        if (ratio < this.significanceThreshold)
+            return null;
+        // Calculate strength (0-1 normalized)
+        const strength = Math.min(1, (ratio - 1) / (this.significanceThreshold * 2));
+        // Confidence based on sample size (logistic curve, plateaus around 20 samples)
+        const confidence = 1 - 1 / (1 + followCount / 10);
+        // Average lag
+        const avgLag = followCount > 0 ? totalLag / followCount : 0;
+        return {
+            cause: causeType,
+            effect: effectType,
+            strength,
+            confidence,
+            lag_ms: avgLag,
+            sample_size: followCount,
+            direction: 1, // cause increases likelihood of effect
+        };
+    }
+    /** Get all detected causal edges (strongest first). */
+    getEdges(minStrength = 0) {
+        return this.db.prepare('SELECT * FROM causal_edges WHERE strength >= ? ORDER BY strength DESC').all(minStrength);
+    }
+    /** Get causes of a specific event type. */
+    getCauses(eventType) {
+        return this.db.prepare('SELECT * FROM causal_edges WHERE effect = ? ORDER BY strength DESC').all(eventType);
+    }
+    /** Get effects of a specific event type. */
+    getEffects(eventType) {
+        return this.db.prepare('SELECT * FROM causal_edges WHERE cause = ? ORDER BY strength DESC').all(eventType);
+    }
+    /** Find causal chains (A → B → C). */
+    findChains(maxDepth = 4) {
+        const edges = this.getEdges(0.1);
+        const adjacency = new Map();
+        for (const edge of edges) {
+            if (!adjacency.has(edge.cause))
+                adjacency.set(edge.cause, []);
+            adjacency.get(edge.cause).push(edge);
+        }
+        const chains = [];
+        const roots = this.findRoots(edges);
+        for (const root of roots) {
+            this.dfs(root, [root], 0, 0, adjacency, maxDepth, new Set(), chains);
+        }
+        // Sort by total strength descending
+        chains.sort((a, b) => b.totalStrength - a.totalStrength);
+        return chains.slice(0, 20); // top 20 chains
+    }
+    /** Full causal analysis including graph structure. */
+    getAnalysis() {
+        const edges = this.getEdges();
+        const roots = this.findRoots(edges);
+        const leaves = this.findLeaves(edges);
+        const chains = this.findChains();
+        return {
+            edges,
+            roots,
+            leaves,
+            strongestChain: chains.length > 0 ? chains[0] : null,
+        };
+    }
+    /** Get event type statistics. */
+    getEventStats() {
+        return this.db.prepare(`
+      SELECT type, COUNT(*) as count,
+             MIN(timestamp) as first_seen,
+             MAX(timestamp) as last_seen
+      FROM causal_events
+      GROUP BY type
+      ORDER BY count DESC
+    `).all();
+    }
+    // ── Private helpers ─────────────────────────────────
+    getEventTypes() {
+        const rows = this.db.prepare('SELECT DISTINCT type FROM causal_events').all();
+        return rows.map(r => r.type);
+    }
+    getTimeRange() {
+        const row = this.db.prepare('SELECT MIN(timestamp) as min_ts, MAX(timestamp) as max_ts FROM causal_events').get();
+        if (!row.min_ts || !row.max_ts)
+            return 0;
+        return row.max_ts - row.min_ts;
+    }
+    upsertEdge(edge) {
+        this.db.prepare(`
+      INSERT INTO causal_edges (cause, effect, strength, confidence, lag_ms, sample_size, direction)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(cause, effect) DO UPDATE SET
+        strength = ?, confidence = ?, lag_ms = ?, sample_size = ?, direction = ?,
+        updated_at = datetime('now')
+    `).run(edge.cause, edge.effect, edge.strength, edge.confidence, edge.lag_ms, edge.sample_size, edge.direction, edge.strength, edge.confidence, edge.lag_ms, edge.sample_size, edge.direction);
+    }
+    findRoots(edges) {
+        const causes = new Set(edges.map(e => e.cause));
+        const effects = new Set(edges.map(e => e.effect));
+        return [...causes].filter(c => !effects.has(c));
+    }
+    findLeaves(edges) {
+        const causes = new Set(edges.map(e => e.cause));
+        const effects = new Set(edges.map(e => e.effect));
+        return [...effects].filter(e => !causes.has(e));
+    }
+    dfs(node, path, totalStrength, totalLag, adjacency, maxDepth, visited, results) {
+        if (path.length >= 3) {
+            // Record any path of length 3+ as a chain
+            results.push({
+                chain: [...path],
+                totalStrength: totalStrength / (path.length - 1), // average strength
+                totalLag,
+            });
+        }
+        if (path.length >= maxDepth)
+            return;
+        const neighbors = adjacency.get(node) ?? [];
+        for (const edge of neighbors) {
+            if (visited.has(edge.effect))
+                continue;
+            visited.add(edge.effect);
+            path.push(edge.effect);
+            this.dfs(edge.effect, path, totalStrength + edge.strength, totalLag + edge.lag_ms, adjacency, maxDepth, visited, results);
+            path.pop();
+            visited.delete(edge.effect);
+        }
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/causal/engine.js.map

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

package/dist/hypothesis/engine.d.ts

@@ -0,0 +1,104 @@
+import type Database from 'better-sqlite3';
+export type HypothesisStatus = 'proposed' | 'testing' | 'confirmed' | 'rejected' | 'inconclusive';
+export interface Hypothesis {
+    id?: number;
+    statement: string;
+    type: string;
+    source: string;
+    variables: string[];
+    condition: HypothesisCondition;
+    status: HypothesisStatus;
+    evidence_for: number;
+    evidence_against: number;
+    confidence: number;
+    p_value: number;
+    created_at?: string;
+    tested_at?: string;
+}
+export interface HypothesisCondition {
+    type: 'temporal' | 'correlation' | 'threshold' | 'frequency';
+    params: Record<string, unknown>;
+}
+export interface HypothesisTestResult {
+    hypothesisId: number;
+    passed: boolean;
+    evidenceFor: number;
+    evidenceAgainst: number;
+    pValue: number;
+    confidence: number;
+    newStatus: HypothesisStatus;
+}
+export interface Observation {
+    source: string;
+    type: string;
+    value: number;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+}
+export declare function runHypothesisMigration(db: Database.Database): void;
+/**
+ * Hypothesis Engine: generates and tests hypotheses autonomously.
+ *
+ * Research approach: The scientific method, automated.
+ *
+ * 1. OBSERVE: Collect observations from all brains
+ * 2. HYPOTHESIZE: Generate hypotheses from patterns in observations
+ *    - Temporal: "Event A occurs more often during time window X"
+ *    - Correlation: "When metric A increases, metric B also increases"
+ *    - Threshold: "Performance degrades when metric A exceeds value X"
+ *    - Frequency: "Event A happens with period P"
+ * 3. TEST: Evaluate hypotheses against historical data using statistical tests
+ * 4. CONCLUDE: Accept or reject based on evidence
+ */
+export declare class HypothesisEngine {
+    private db;
+    private logger;
+    private minEvidence;
+    private confirmThreshold;
+    private rejectThreshold;
+    constructor(db: Database.Database, config?: {
+        minEvidence?: number;
+        confirmThreshold?: number;
+        rejectThreshold?: number;
+    });
+    /** Record an observation for hypothesis generation and testing. */
+    observe(observation: Observation): void;
+    /** Propose a hypothesis manually or from automated detection. */
+    propose(hypothesis: Omit<Hypothesis, 'id' | 'status' | 'evidence_for' | 'evidence_against' | 'confidence' | 'p_value' | 'created_at' | 'tested_at'>): Hypothesis;
+    /**
+     * Auto-generate hypotheses from observation patterns.
+     * This is the creative part — the system forms its own theories.
+     */
+    generate(): Hypothesis[];
+    /**
+     * Test a hypothesis against available data.
+     * Returns the test result with updated status.
+     */
+    test(hypothesisId: number): HypothesisTestResult | null;
+    /** Test all proposed/testing hypotheses. */
+    testAll(): HypothesisTestResult[];
+    /** Get a hypothesis by ID. */
+    get(id: number): Hypothesis | null;
+    /** List hypotheses by status. */
+    list(status?: HypothesisStatus, limit?: number): Hypothesis[];
+    /** Get summary statistics. */
+    getSummary(): {
+        total: number;
+        proposed: number;
+        testing: number;
+        confirmed: number;
+        rejected: number;
+        inconclusive: number;
+        totalObservations: number;
+        topConfirmed: Hypothesis[];
+    };
+    private generateTemporalHypotheses;
+    private generateCorrelationHypotheses;
+    private generateThresholdHypotheses;
+    private testTemporalHypothesis;
+    private testCorrelationHypothesis;
+    private testThresholdHypothesis;
+    private testFrequencyHypothesis;
+    private getObservationTypes;
+    private getObservationTimeRange;
+}