feat: Causal Reasoning

[lsm]

Purpose

Enable NeoKai to understand cause-and-effect relationships, predict action consequences, and perform root cause analysis when things go wrong. This is essential for AGI-level autonomy because:

• Predictive capability: Anticipating what will happen before acting
• Root cause analysis: Understanding why failures occurred
• Counterfactual reasoning: Evaluating alternative scenarios
• Intervention planning: Designing effective solutions

Without causal reasoning, NeoKai cannot reliably predict outcomes or explain failures.

---

Current State

NeoKai has:

• No explicit causal model
• No action-effect prediction
• No counterfactual reasoning
• No systematic root cause analysis

Action → Result mapping is implicit and not reasoned about.

---

Proposed Approach

Phase 1: Causal Model Framework

1. Causal Graph Structure

   interface CausalNode {
     id: string;
     type: 'variable' | 'action' | 'outcome';
     name: string;
     description: string;
     possibleStates: string[];
   }
   
   interface CausalEdge {
     from: string;  // Node ID
     to: string;    // Node ID
     relationship: 'causes' | 'enables' | 'prevents' | 'influences';
     strength: number;  // 0-1, how strong is the causal relationship
     conditions?: string[];  // When this causal relationship applies
   }
   
   interface CausalModel {
     nodes: Map<string, CausalNode>;
     edges: CausalEdge[];
     
     // Query the model
     query(query: CausalQuery): Promise<CausalResult>;
   }

2. Built-in Causal Knowledge

   const builtInCausalKnowledge = {
     // Code changes
     codeChange: {
       causes: ['behavior_change'],
       influencedBy: ['change_type', 'code_location', 'test_coverage']
     },
     
     // Test failures
     testFailure: {
       causedBy: ['code_bug', 'test_bug', 'environment_issue', 'dependency_change'],
       indicates: ['incorrect_behavior', 'broken_contract']
     },
     
     // Performance changes
     performanceChange: {
       causedBy: ['algorithm_change', 'data_volume_change', 'resource_limitation'],
       measuredBy: ['latency', 'throughput', 'memory_usage']
     },
     
     // Build failures
     buildFailure: {
       causedBy: ['syntax_error', 'type_error', 'missing_dependency', 'config_error'],
       prevents: ['deployment', 'testing']
     }
   };

Phase 2: Action-Effect Prediction

1. Prediction Engine

   interface EffectPredictor {
     // Predict effects of an action
     predict(action: Action, context: Context): Promise<PredictedEffects>;
     
     // Predict multiple possible outcomes with probabilities
     predictProbabilistic(
       action: Action,
       context: Context
     ): Promise<ProbabilisticOutcome[]>;
   }
   
   interface PredictedEffects {
     primaryEffects: Effect[];
     sideEffects: Effect[];
     secondaryEffects: Effect[];
     probabilities: Map<string, number>;
   }
   
   interface Effect {
     description: string;
     affectedNode: string;
     expectedChange: string;
     confidence: number;
     reversibility: 'reversible' | 'partially_reversible' | 'irreversible';
   }

2. Prediction Patterns

   const predictionPatterns = {
     // When you modify a function...
     functionModification: {
       primaryEffects: [
         'behavior_change_in_callers',
         'test_may_need_update'
       ],
       sideEffects: [
         'type_errors_if_signature_changed',
         'documentation_drift'
       ],
       confidence: {
         high: ['well_tested_function', 'few_callers'],
         low: ['complex_function', 'many_callers', 'unclear_usage']
       }
     },
     
     // When you add a dependency...
     dependencyAddition: {
       primaryEffects: [
         'new_capabilities_available',
         'bundle_size_increase'
       ],
       sideEffects: [
         'potential_security_vulnerability',
         'maintenance_burden',
         'license_compatibility_check_needed'
       ]
     },
     
     // When you delete code...
     codeDeletion: {
       primaryEffects: [
         'dead_code_removal',
         'potential_breaking_change'
       ],
       sideEffects: [
         'broken_imports_if_still_used',
         'test_failures_if_covered_deleted_code'
       ]
     }
   };

3. Prediction Integration

   interface PredictionIntegrator {
     // Integrate predictions into decision making
     integrate(
       predictions: PredictedEffects,
       decision: Decision
     ): EnhancedDecision;
   }
   
   // Use predictions to:
   // - Warn about potential issues before action
   // - Suggest mitigations for predicted side effects
   // - Recommend safer alternatives

Phase 3: Root Cause Analysis

1. Analysis Framework

   interface RootCauseAnalyzer {
     // Analyze why something happened
     analyze(effect: Effect, context: Context): Promise<RootCauseResult>;
     
     // Drill down into causes
     drillDown(cause: Cause): Promise<DeeperAnalysis>;
   }
   
   interface RootCauseResult {
     primaryCause: Cause;
     contributingFactors: Cause[];
     causalChain: CausalStep[];
     confidence: number;
     recommendations: Recommendation[];
   }
   
   interface CausalStep {
     cause: string;
     effect: string;
     evidence: string;
     confidence: number;
   }

2. Analysis Strategies

   const analysisStrategies = {
     // Five Whys technique
     fiveWhys: {
       maxDepth: 5,
       questions: ['why did {effect} happen?']
     },
     
     // Fishbone diagram
     fishbone: {
       categories: ['people', 'process', 'tools', 'environment', 'code'],
       generateHypotheses: true
     },
     
     // Differential diagnosis
     differentialDiagnosis: {
       considerAll: true,
       ruleOutWith: ['evidence', 'tests', 'logs']
     },
     
     // Temporal analysis
     temporal: {
       lookFor: ['changes_before', 'correlations', 'anomalies']
     }
   };

3. Analysis Examples

   const analysisExamples = {
     testFailureAnalysis: {
       symptom: 'Test "user login" is failing',
       
       causalChain: [
         {
           cause: 'Login returns 500 error',
           effect: 'Test assertion fails',
           evidence: 'Error logs show 500'
         },
         {
           cause: 'Database connection timeout',
           effect: 'Login endpoint fails',
           evidence: 'DB logs show timeout'
         },
         {
           cause: 'Connection pool exhausted',
           effect: 'Database connections timeout',
           evidence: 'Pool metrics show 100% usage'
         },
         {
           cause: 'New feature increased DB queries',
           effect: 'Connection pool exhausted',
           evidence: 'Recent commit added queries without pool resize'
         }
       ],
       
       rootCause: 'Connection pool not resized for new query load',
       recommendations: [
         'Increase connection pool size',
         'Add connection pool monitoring',
         'Review queries for optimization'
       ]
     }
   };

Phase 4: Counterfactual Reasoning

1. Counterfactual Engine

   interface CounterfactualEngine {
     // What would have happened if X?
     whatIf(
       actualScenario: Scenario,
       alternativeAction: Action
     ): Promise<CounterfactualResult>;
     
     // Compare multiple scenarios
     compare(
       scenarios: Scenario[]
     ): Promise<ComparisonResult>;
   }
   
   interface CounterfactualResult {
     alternative: string;
     predictedOutcome: string;
     differencesFromActual: Difference[];
     confidence: number;
   }

2. Use Cases

   const counterfactualUseCases = {
     // Learning from failures
     postMortem: {
       question: 'What if we had done X instead?',
       purpose: 'Identify better approaches for future'
     },
     
     // Pre-decision analysis
     decisionSupport: {
       question: 'What would happen if we choose X vs Y?',
       purpose: 'Make better decisions'
     },
     
     // Understanding causality
     causalUnderstanding: {
       question: 'Was X necessary for outcome Y?',
       purpose: 'Verify causal relationships'
     }
   };

3. Counterfactual Generation

   interface CounterfactualGenerator {
     // Generate plausible alternatives
     generate(
       scenario: Scenario,
       variables: string[]
     ): Promise<CounterfactualScenario[]>;
   }
   
   // Example:
   // Actual: "Used opus for all tasks, spent $50"
   // Counterfactuals:
   // - "Used haiku for simple tasks, would have spent $20"
   // - "Used sonnet for most tasks, would have spent $35"
   // - "Batched tasks, would have spent $40"

Phase 5: Side Effect Prediction

1. Side Effect Detector

   interface SideEffectDetector {
     // Detect potential side effects
     detect(action: Action, model: CausalModel): Promise<SideEffect[]>;
     
     // Estimate side effect probability
     estimateProbability(
       sideEffect: SideEffect,
       context: Context
     ): number;
   }
   
   interface SideEffect {
     description: string;
     affectedComponents: string[];
     probability: number;
     severity: 'minor' | 'moderate' | 'major' | 'critical';
     mitigation: string;
   }

2. Common Side Effects

   const commonSideEffects = {
     codeChange: {
       breakExistingTests: { probability: 0.3, severity: 'moderate' },
       introduceBugs: { probability: 0.1, severity: 'major' },
       performanceRegression: { probability: 0.15, severity: 'moderate' },
       documentationDrift: { probability: 0.5, severity: 'minor' }
     },
     
     dependencyChange: {
       breakCompatibility: { probability: 0.2, severity: 'major' },
       securityVulnerability: { probability: 0.05, severity: 'critical' },
       bundleSizeIncrease: { probability: 0.3, severity: 'minor' },
       transitiveDependencyIssues: { probability: 0.15, severity: 'moderate' }
     },
     
     configurationChange: {
       environmentIssues: { probability: 0.2, severity: 'major' },
       securityMisconfiguration: { probability: 0.1, severity: 'critical' },
       performanceImpact: { probability: 0.15, severity: 'moderate' }
     }
   };

Phase 6: Intervention Planning

1. Intervention Designer

   interface InterventionDesigner {
     // Design intervention to achieve outcome
     design(
       currentState: State,
       desiredOutcome: Outcome,
       model: CausalModel
     ): Promise<InterventionPlan>;
     
     // Find minimal intervention
     findMinimal(
       currentState: State,
       desiredOutcome: Outcome
     ): Promise<InterventionPlan>;
   }
   
   interface InterventionPlan {
     interventions: Intervention[];
     expectedOutcome: Outcome;
     sideEffects: SideEffect[];
     confidence: number;
     rollbackPlan?: InterventionPlan;
   }
   
   interface Intervention {
     action: Action;
     target: string;  // What node in causal model
     expectedEffect: string;
     prerequisites: string[];
   }

2. Intervention Strategies

   const interventionStrategies = {
     // Fix root cause
     rootCauseFix: {
       approach: 'Address underlying cause',
       example: 'Increase connection pool to fix timeout'
     },
     
     // Break causal chain
     chainBreak: {
       approach: 'Intervene at a point in the chain',
       example: 'Add caching to prevent DB overload'
     },
     
     // Add compensating action
     compensation: {
       approach: 'Add action that counteracts effect',
       example: 'Add retry logic for transient failures'
     },
     
     // Change conditions
     conditionChange: {
       approach: 'Change context so cause no longer produces effect',
       example: 'Move to environment with more resources'
     }
   };

Phase 7: Learning Causal Relationships

1. Causal Learning

   interface CausalLearner {
     // Learn from observed outcomes
     learn(observations: Observation[]): Promise<CausalRule>;
     
     // Update causal model
     updateModel(
       model: CausalModel,
       rule: CausalRule
     ): Promise<CausalModel>;
   }
   
   interface CausalRule {
     cause: string;
     effect: string;
     conditions: string[];
     confidence: number;
     evidenceCount: number;
   }

2. Learning from Experience

   const learningSources = {
     // Direct observation
     observation: {
       source: 'actual outcomes',
       reliability: 'high'
     },
     
     // User feedback
     userFeedback: {
       source: 'user correction',
       reliability: 'high'
     },
     
     // Inferred from patterns
     patternInference: {
       source: 'statistical patterns',
       reliability: 'medium'
     },
     
     // Domain knowledge
     domainKnowledge: {
       source: 'documentation/experts',
       reliability: 'varies'
     }
   };

---

Technical Considerations

Model Complexity

• Balancing detail with tractability
• Handling uncertainty in causal relationships
• Managing model size

Prediction Accuracy

• Calibrating prediction confidence
• Handling novel situations
• Learning from prediction errors

Analysis Depth

• When to stop drilling down
• Balancing thoroughness with speed
• Handling ambiguous causality

Learning Reliability

• Avoiding spurious correlations
• Handling confounding variables
• Validating learned rules

---

Success Metrics

1. Prediction Accuracy: % of accurate effect predictions
2. Root Cause Identification: % of correct root cause identification
3. Intervention Effectiveness: Success rate of planned interventions
4. Learning Rate: Improvement in causal model over time

---

Implementation Roadmap

1. Phase 1: Basic causal model framework
2. Phase 2: Action-effect prediction
3. Phase 3: Root cause analysis
4. Phase 4: Counterfactual reasoning
5. Phase 5: Side effect prediction
6. Phase 6: Intervention planning
7. Phase 7: Causal learning

---

Questions for Discussion

1. How detailed should the causal model be?
2. How to handle situations with unclear causality?
3. Should causal knowledge be shared across projects?
4. How to validate causal rules before adding to model?

---

Part of the AGI-Level Autonomy initiative