@yun520-1/heartflow 0.15.2 → 0.16.0

package/src/core/reasoning/bounded-rationality.ts

@@ -1,342 +0,0 @@
-/**
- * HeartFlow Decision Engine — Bounded Rationality Module
- * Based on: "Beyond Nash Equilibrium: Bounded Rationality of LLMs and Humans"
- * (Zheng et al., arXiv:2506.09390, Tsinghua CoAI Group)
- *
- * Key insights:
- * - LLMs show human-like bounded rationality: outcome-based strategy switching
- * - LLMs are MORE RIGID than humans in applying heuristics
- * - Key patterns: WSLU (win-stay/lose-upgrade), WDLS (win-downgrade/lose-stay)
- * - "Shadow of future" effect: LLMs over-respond to future-oriented framing
- * - Weak environmental sensitivity: LLMs don't adapt well to changing game structure
- */
-
-import type { MemoryEntry } from '../memory/memory.js';
-
-// ── Types ─────────────────────────────────────────────────────────────────────
-
-export type HeuristicType =
-  | 'WSLU'   // Win-Stay/Lose-Upgrade: win→same action, lose→upgrade
-  | 'WDLS'   // Win-Downgrade/Lose-Stay: win→weaker action, lose→same
-  | 'RANDOM' // Random exploration
-  | 'NASH';  // Pure Nash equilibrium (for reference)
-
-export interface GameOutcome {
-  action: string;
-  result: 'WIN' | 'LOSE' | 'TIE';
-  reward: number;
-  timestamp: number;
-}
-
-export interface StrategyState {
-  name: string;
-  lastAction: string | null;
-  lastOutcome: GameOutcome | null;
-  actionHistory: string[];
-  outcomeHistory: GameOutcome[];
-  heuristicsUsed: HeuristicType[];
-  environmentalSensitivity: number;  // 0-1, how quickly adapts to environment changes
-  rigidityScore: number;            // 0-1, how rigidly it applies heuristics
-}
-
-export interface BoundedRationalityReport {
-  strategyState: StrategyState;
-  detectedHeuristics: HeuristicType[];
-  rigidityAssessment: {
-    score: number;         // 0-1, higher = more rigid
-    comparedToHuman: string;
-    recommendation: string;
-  };
-  shadowOfFutureBias: {
-    present: boolean;
-    exaggerationFactor: number;  // how much LLM over-responds to future framing
-    description: string;
-  };
-  environmentalAdaptation: {
-    score: number;         // 0-1, how well it adapts
-    detectedChange: boolean;
-    adaptationSpeed: 'fast' | 'medium' | 'slow' | 'none';
-  };
-  nextRecommendedAction: string;
-  reasoningTrace: string[];
-}
-
-// ── Constants ─────────────────────────────────────────────────────────────────
-
-const HEURISTIC_THRESHOLDS = {
-  STAY_PROBABILITY: 0.6,      // if WIN and P(stay) > this, heuristic = WSLU
-  UPGRADE_PROBABILITY: 0.6,  // if LOSE and P(upgrade) > this, heuristic = WSLU
-  DOWNGRADE_THRESHOLD: 0.5,   // if WIN and P(downgrade) > this, heuristic = WDLS
-  RIGIDITY_SCALE: 0.7,        // if same heuristic used >70% of time, rigid
-  ENVIRONMENT_CHANGE_WINDOW: 5, // detect environment change within last N rounds
-};
-
-const ACTIONS = ['ROCK', 'PAPER', 'SCISSORS'];
-
-// ── Strategy State Factory ─────────────────────────────────────────────────────
-
-export function createStrategyState(name: string): StrategyState {
-  return {
-    name,
-    lastAction: null,
-    lastOutcome: null,
-    actionHistory: [],
-    outcomeHistory: [],
-    heuristicsUsed: [],
-    environmentalSensitivity: 0.5,
-    rigidityScore: 0,
-  };
-}
-
-// ── Core Decision Functions ────────────────────────────────────────────────────
-
-function getActionIndex(action: string): number {
-  return ACTIONS.indexOf(action);
-}
-
-function getGameResult(myAction: string, oppAction: string): GameOutcome['result'] {
-  const m = getActionIndex(myAction);
-  const o = getActionIndex(oppAction);
-  if (m === o) return 'TIE';
-  if ((m + 1) % 3 === o) return 'WIN';
-  return 'LOSE';
-}
-
-function getCounterAction(action: string): string {
-  // Returns the action that beats the given action
-  const i = getActionIndex(action);
-  return ACTIONS[(i + 1) % 3];
-}
-
-function getWeakerAction(action: string): string {
-  // Returns the action that loses to the given action
-  const i = getActionIndex(action);
-  return ACTIONS[(i + 2) % 3];
-}
-
-/**
- * Detect which heuristic is being used based on outcome history
- */
-export function detectHeuristic(state: StrategyState): HeuristicType {
-  if (state.outcomeHistory.length < 3) return 'RANDOM';
-
-  const recent = state.outcomeHistory.slice(-5);
-  let wsluCount = 0;
-  let wdlsCount = 0;
-
-  for (let i = 1; i < recent.length; i++) {
-    const prev = recent[i - 1];
-    const curr = recent[i];
-
-    if (prev.result === 'WIN' && curr.result === 'WIN') {
-      // WIN-WIN: stayed same action → WSLU pattern
-      if (state.actionHistory[state.actionHistory.length - (recent.length - i)] ===
-          state.actionHistory[state.actionHistory.length - (recent.length - i) + 1]) {
-        wsluCount++;
-      }
-    }
-    if (prev.result === 'LOSE' && curr.result === 'LOSE') {
-      // LOSE-LOSE: didn't change action → might be WDLS failing
-      wdlsCount++;
-    }
-    if (prev.result === 'WIN' && curr.result === 'LOSE') {
-      // WIN-LOSE: win then lose → might have upgraded (WSLU would stay on win)
-      const prevAction = state.actionHistory[state.actionHistory.length - (recent.length - i)];
-      const currAction = state.actionHistory[state.actionHistory.length - (recent.length - i) + 1];
-      if (prevAction !== currAction) wsluCount++; // changed after win
-    }
-  }
-
-  if (wsluCount > wdlsCount && wsluCount >= 2) return 'WSLU';
-  if (wdlsCount > wsluCount && wdlsCount >= 2) return 'WDLS';
-  return 'RANDOM';
-}
-
-/**
- * Calculate rigidity score: how consistently the same heuristic is applied
- */
-export function calculateRigidityScore(heuristicsUsed: HeuristicType[]): number {
-  if (heuristicsUsed.length < 3) return 0;
-
-  const counts = new Map<HeuristicType, number>();
-  for (const h of heuristicsUsed) {
-    counts.set(h, (counts.get(h) ?? 0) + 1);
-  }
-
-  const maxCount = Math.max(...Array.from(counts.values()));
-  return maxCount / heuristicsUsed.length;
-}
-
-/**
- * Detect environmental change: if opponent strategy shifts noticeably
- */
-export function detectEnvironmentChange(actionHistory: string[], outcomeHistory: GameOutcome[]): boolean {
-  if (actionHistory.length < HEURISTIC_THRESHOLDS.ENVIRONMENT_CHANGE_WINDOW * 2) {
-    return false;
-  }
-
-  const recent = actionHistory.slice(-HEURISTIC_THRESHOLDS.ENVIRONMENT_CHANGE_WINDOW);
-  const previous = actionHistory.slice(
-    -HEURISTIC_THRESHOLDS.ENVIRONMENT_CHANGE_WINDOW * 2,
-    -HEURISTIC_THRESHOLDS.ENVIRONMENT_CHANGE_WINDOW
-  );
-
-  // Calculate action distribution shift
-  const distShift = calculateDistributionShift(recent, previous);
-  return distShift > 0.4; // 40% distribution change = environment change
-}
-
-function calculateDistributionShift(a: string[], b: string[]): number {
-  const allActions = Array.from(new Set([...a, ...b]));
-  const distA = allActions.map(action => a.filter(x => x === action).length / a.length);
-  const distB = b.length > 0 ? allActions.map(action => b.filter(x => x === action).length / b.length) : distA;
-
-  let shift = 0;
-  for (let i = 0; i < allActions.length; i++) {
-    shift += Math.abs(distA[i] - (distB[i] || 0));
-  }
-  return shift / 2; // 0 = no change, 1 = completely different
-}
-
-/**
- * Generate next action based on bounded rationality principles
- */
-export function decideNextAction(state: StrategyState): string {
-  const detected = detectHeuristic(state);
-
-  if (detected === 'WSLU') {
-    // Win-Stay/Lose-Upgrade: if won, stay; if lost, upgrade (counter action)
-    if (state.lastOutcome?.result === 'WIN' && state.lastAction) {
-      return state.lastAction; // stay
-    }
-    if (state.lastOutcome?.result === 'LOSE' && state.lastAction) {
-      return getCounterAction(state.lastAction); // upgrade
-    }
-  }
-
-  if (detected === 'WDLS') {
-    // Win-Downgrade/Lose-Stay: if won, weaken; if lost, stay
-    if (state.lastOutcome?.result === 'WIN' && state.lastAction) {
-      return getWeakerAction(state.lastAction); // downgrade
-    }
-    if (state.lastOutcome?.result === 'LOSE' && state.lastAction) {
-      return state.lastAction; // stay
-    }
-  }
-
-  // Default: random with slight Nash preference (equal distribution)
-  return ACTIONS[Math.floor(Math.random() * ACTIONS.length)];
-}
-
-/**
- * Full bounded rationality assessment
- */
-export function assessBoundedRationality(
-  state: StrategyState,
-  opponentLastAction?: string
-): BoundedRationalityReport {
-  const detected = detectHeuristic(state);
-  const rigidity = calculateRigidityScore(state.heuristicsUsed);
-  const envChange = detectEnvironmentChange(state.actionHistory, state.outcomeHistory);
-
-  // Shadow of future bias detection
-  // If cooperation increases with "future" framing even when structurally equivalent → bias
-  const shadowBiasPresent = state.outcomeHistory.length >= 5 &&
-    state.outcomeHistory.slice(-5).filter(o => o.result === 'WIN').length >= 3;
-
-  const nextAction = decideNextAction(state);
-
-  const reasoningTrace = [
-    `Detected heuristic: ${detected}`,
-    `Rigidity score: ${(rigidity * 100).toFixed(0)}%`,
-    `Environment change detected: ${envChange}`,
-    `Last outcome: ${state.lastOutcome?.result ?? 'N/A'}`,
-    `Recommended action: ${nextAction}`,
-  ];
-
-  return {
-    strategyState: { ...state },
-    detectedHeuristics: [detected],
-    rigidityAssessment: {
-      score: rigidity,
-      comparedToHuman: rigidity > 0.7
-        ? 'More rigid than typical human behavior'
-        : 'Similar flexibility to human bounded rationality',
-      recommendation: rigidity > 0.7
-        ? 'Consider diversifying strategy to reduce predictability'
-        : 'Current heuristic application is within normal range',
-    },
-    shadowOfFutureBias: {
-      present: shadowBiasPresent,
-      exaggerationFactor: shadowBiasPresent ? 1.3 : 1.0, // LLMs typically 1.2-1.5x
-      description: shadowBiasPresent
-        ? 'Detected tendency to over-respond to future-oriented framing'
-        : 'No significant shadow-of-future bias detected',
-    },
-    environmentalAdaptation: {
-      score: envChange ? Math.max(0, 0.5 - rigidity * 0.3) : 0.8,
-      detectedChange: envChange,
-      adaptationSpeed: envChange
-        ? (rigidity > 0.7 ? 'slow' : rigidity > 0.4 ? 'medium' : 'fast')
-        : 'none',
-    },
-    nextRecommendedAction: nextAction,
-    reasoningTrace,
-  };
-}
-
-/**
- * Record a new decision round
- */
-export function recordRound(
-  state: StrategyState,
-  action: string,
-  opponentAction: string,
-  reward: number
-): StrategyState {
-  const result = getGameResult(action, opponentAction);
-  const outcome: GameOutcome = {
-    action,
-    result,
-    reward,
-    timestamp: Date.now(),
-  };
-
-  const newState = { ...state };
-  newState.actionHistory = [...state.actionHistory, action];
-  newState.outcomeHistory = [...state.outcomeHistory, outcome];
-  newState.lastAction = action;
-  newState.lastOutcome = outcome;
-
-  // Update heuristics tracking
-  const detected = detectHeuristic(newState);
-  newState.heuristicsUsed = [...state.heuristicsUsed, detected];
-  if (newState.heuristicsUsed.length > 50) {
-    newState.heuristicsUsed = newState.heuristicsUsed.slice(-50);
-  }
-
-  // Update rigidity score
-  newState.rigidityScore = calculateRigidityScore(newState.heuristicsUsed);
-
-  // Update environmental sensitivity based on recent history
-  newState.environmentalSensitivity = envSensitivityFromHistory(newState.outcomeHistory);
-
-  return newState;
-}
-
-function envSensitivityFromHistory(outcomes: GameOutcome[]): number {
-  if (outcomes.length < 10) return 0.5;
-
-  // Look for variance in outcomes - high variance = environment is changing
-  const results = outcomes.slice(-10).map(o => o.result);
-  const wins = results.filter(r => r === 'WIN').length;
-  const losses = results.filter(r => r === 'LOSE').length;
-  const ties = results.filter(r => r === 'TIE').length;
-
-  const total = results.length;
-  const entropy = -(wins/total * Math.log2(wins/total + 0.01) +
-                    losses/total * Math.log2(losses/total + 0.01) +
-                    ties/total * Math.log2(ties/total + 0.01));
-
-  return Math.min(1, entropy / 1.5); // normalized
-}