jev-chess 1.0.0

package/src/gameReviewer.ts

@@ -0,0 +1,113 @@
+import type { ChessEngine } from "./chessEngine.js";
+import { choice, getTypeSafeClient, score } from "./typeSafeClient.js";
+import type { AnnotatedMove, BlunderDiagnosis, MistakeArchetype } from "./types.js";
+
+const MISTAKE_ARCHETYPES: Record<MistakeArchetype, string> = {
+  sound_move: "A solid, principled move with no critical defect",
+  tactical_blindness: "Overlooked an immediate tactical blow, fork, pin, skewer, or check",
+  poisoned_pawn_greed: "Grabbed material at the fatal expense of development or king safety",
+  over_extension: "Pushed pawns or pieces too far forward, creating irreparable structural holes",
+  passive_concession: "Retreated timidly, yielding tempo and spatial dominance to the opponent",
+  king_safety_negligence: "Compromised the pawn shield or exposed the monarch to a deadly storm",
+};
+
+const DEFENSIVE_DIFFICULTY_RUBRIC = [
+  "Comfortable defense; natural and straightforward moves maintain balance",
+  "Tense defense; requires disciplined calculation and piece coordination",
+  "Precise tightrope; requires narrow, counter-intuitive only-moves to survive",
+  "Hopeless or practically impossible for a human player to defend under pressure",
+] as const;
+
+const TENSION_RUBRIC = [
+  "Peaceful and quiet; strategic maneuvering behind closed lines",
+  "Building central friction and contested outposts",
+  "Sharp tactical skirmish; pieces in contact and multiple captures pending",
+  "Decisive boiling point; mutual king attacks and explosive complications",
+] as const;
+
+/**
+ * Diagnostic Game Reviewer that classifies chess moves and blunders into actionable semantic concepts.
+ * Pattern: Verification & Escalation / Structured Diagnostics.
+ */
+export class GameReviewer {
+  private get client() {
+    return getTypeSafeClient();
+  }
+
+  public async diagnoseMove(
+    engine: ChessEngine,
+    move: AnnotatedMove,
+    moveNumber: number
+  ): Promise<BlunderDiagnosis> {
+    const boardContext = engine.getBoardContext();
+
+    const state = {
+      game_state: {
+        fen: boardContext.fen,
+        turn: boardContext.turn,
+        phase: boardContext.gamePhase,
+        material: boardContext.materialBalance.description,
+        recent_moves: boardContext.recentHistory,
+      },
+      played_move: {
+        san: move.san,
+        description: move.description,
+        is_capture: move.isCapture,
+        is_check: move.isCheck,
+      },
+    };
+
+    const response = await this.client.systemOne({
+      state,
+      questions: {
+        archetype: choice(
+          "Which mistake or positional category best describes `played_move.san`?",
+          MISTAKE_ARCHETYPES
+        ),
+        defensive_difficulty: score(
+          "How difficult is it to defend or recover from this position after `played_move.san`?",
+          DEFENSIVE_DIFFICULTY_RUBRIC
+        ),
+        tension: score(
+          "What is the overall tactical and psychological tension level on the board?",
+          TENSION_RUBRIC
+        ),
+      },
+    });
+
+    const archetypeChoice = response.answers.archetype.choice as MistakeArchetype;
+    const diffScore = response.answers.defensive_difficulty.score;
+    const tensionScore = response.answers.tension.score;
+
+    let coachAdvice = "Keep developing actively and control the center.";
+    switch (archetypeChoice) {
+      case "tactical_blindness":
+        coachAdvice = "Always scan for opponent checks, captures, and threats before finalizing your move.";
+        break;
+      case "poisoned_pawn_greed":
+        coachAdvice = "Do not go pawn hunting with an uncastled king or uncoordinated pieces!";
+        break;
+      case "over_extension":
+        coachAdvice = "Pawns cannot move backwards; every advance creates irreversible weaknesses.";
+        break;
+      case "passive_concession":
+        coachAdvice = "When pushed, look for counter-attacking resources rather than passive retreats.";
+        break;
+      case "king_safety_negligence":
+        coachAdvice = "Castling and securing your king should take priority over peripheral adventures.";
+        break;
+      case "sound_move":
+        coachAdvice = "Excellent, harmonious play. Continue executing your strategic plan.";
+        break;
+    }
+
+    return {
+      moveNumber,
+      playedMove: move.san,
+      mistakeArchetype: archetypeChoice,
+      defensiveDifficulty: diffScore,
+      tacticalTension: tensionScore,
+      coachAdvice,
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./chessEngine.js";
+export * from "./typeSafeClient.js";
+export * from "./moveResolver.js";
+export * from "./moveEvaluator.js";
+export * from "./personaEngine.js";
+export * from "./gameReviewer.js";
+export * from "./classicMatches.js";

package/src/moveEvaluator.ts

@@ -0,0 +1,122 @@
+import type { ChessEngine } from "./chessEngine.js";
+import { choice, getTypeSafeClient, noul, score } from "./typeSafeClient.js";
+import type { AnnotatedMove, MoveEvaluation } from "./types.js";
+
+const SHARPNESS_RUBRIC = [
+  "Quiet, solid, or prophylactic maneuver with minimal immediate confrontation",
+  "Normal central development or positional consolidation",
+  "Sharp or provocative move with direct tactical tension",
+  "High-risk sacrifice or explosive tactical clash",
+] as const;
+
+const STRATEGIC_THEMES = {
+  pawn_break: "Advances a pawn to challenge or dissolve opponent pawn structure",
+  piece_activation: "Develops or repositions a piece to an active central or attacking square",
+  prophylaxis: "Prevents opponent's plan, stabilizes position, or secures king safety",
+  tactical_strike: "Direct capture, check, fork, pin, or tactic to win material or mate",
+  king_hunt: "Advances pieces or pawns directly against the enemy king",
+  simplification: "Trades pieces to consolidate advantage or clarify position",
+};
+
+/**
+ * Multi-dimensional qualitative evaluator for chess moves using TypeSafe AI.
+ * Pattern: Parallel Atomic Judgments + Code-Controlled Badge Synthesis.
+ */
+export class MoveEvaluator {
+  private get client() {
+    return getTypeSafeClient();
+  }
+
+  public async evaluateMove(
+    engine: ChessEngine,
+    move: AnnotatedMove
+  ): Promise<MoveEvaluation> {
+    const boardContext = engine.getBoardContext();
+
+    const state = {
+      evaluated_move: {
+        san: move.san,
+        description: move.description,
+        is_capture: move.isCapture,
+        is_check: move.isCheck,
+        piece: move.piece,
+      },
+      board_context: {
+        fen: boardContext.fen,
+        turn: boardContext.turn,
+        game_phase: boardContext.gamePhase,
+        material: boardContext.materialBalance.description,
+        recent_history: boardContext.recentHistory,
+      },
+    };
+
+    // Parallel atomic evaluation in a single round-trip
+    const response = await this.client.systemOne({
+      state,
+      questions: {
+        tactical_sharpness: score(
+          "How sharp, tactical, or double-edged is the move `evaluated_move.san` in this position?",
+          SHARPNESS_RUBRIC
+        ),
+        strategic_theme: choice(
+          "Which primary strategic or tactical theme best characterizes `evaluated_move.san`?",
+          STRATEGIC_THEMES
+        ),
+        king_attack: noul(
+          "Does `evaluated_move.san` initiate or advance a direct attack against the enemy king?"
+        ),
+        psychological_pressure: noul(
+          "Is `evaluated_move.san` a provocative or high-pressure move that challenges the opponent mentally?"
+        ),
+      },
+    });
+
+    const sharpnessAnswer = response.answers.tactical_sharpness;
+    const themeAnswer = response.answers.strategic_theme;
+    const kingAnswer = response.answers.king_attack;
+    const pressureAnswer = response.answers.psychological_pressure;
+
+    const sharpnessScore = sharpnessAnswer.score;
+    const sharpnessLevel =
+      SHARPNESS_RUBRIC[Math.min(SHARPNESS_RUBRIC.length - 1, Math.round(sharpnessScore))] ??
+      "Standard move";
+
+    // Determine commentary badge in deterministic code (clean, professional text)
+    let commentaryBadge = "Standard Move";
+    if (sharpnessScore >= 2.2) {
+      commentaryBadge = "Sharp Tactical Clash";
+    } else if (kingAnswer.noul >= 0.7) {
+      commentaryBadge = "King Assault Initiated";
+    } else if (themeAnswer.choice === "prophylaxis") {
+      commentaryBadge = "Prophylactic Squeeze";
+    } else if (themeAnswer.choice === "pawn_break") {
+      commentaryBadge = "Central Pawn Break";
+    } else if (themeAnswer.choice === "simplification") {
+      commentaryBadge = "Positional Simplification";
+    } else if (sharpnessScore <= 0.6) {
+      commentaryBadge = "Calm Positional Maneuver";
+    } else {
+      commentaryBadge = "Piece Activation";
+    }
+
+    return {
+      san: move.san,
+      tacticalSharpness: {
+        score: sharpnessScore,
+        level: sharpnessLevel,
+        confidence: sharpnessAnswer.confidence,
+      },
+      strategicTheme: {
+        theme: themeAnswer.choice,
+        confidence: themeAnswer.confidence,
+      },
+      kingAttackRisk: {
+        probability: kingAnswer.noul,
+      },
+      psychologicalPressure: {
+        probability: pressureAnswer.noul,
+      },
+      commentaryBadge,
+    };
+  }
+}

package/src/moveResolver.ts

@@ -0,0 +1,120 @@
+import type { ChessEngine } from "./chessEngine.js";
+import { choice, getTypeSafeClient } from "./typeSafeClient.js";
+import type { AnnotatedMove, MoveIntentResult } from "./types.js";
+
+/**
+ * Resolves natural language user commands into exact legal chess moves using TypeSafe Choice.
+ * Pattern: Select Instead of Generate + Confidence-Gated Ambiguity Resolution.
+ */
+export class MoveResolver {
+  private get client() {
+    return getTypeSafeClient();
+  }
+
+  /**
+   * Resolves natural language intent (e.g. "push my e-pawn two squares", "castle kingside")
+   * into a verified legal move.
+   */
+  public async resolveIntent(
+    engine: ChessEngine,
+    userQuery: string,
+    confidenceThreshold = 0.55
+  ): Promise<MoveIntentResult> {
+    const candidates = engine.getAnnotatedMoves();
+
+    if (candidates.length === 0) {
+      return {
+        query: userQuery,
+        matchedMove: null,
+        san: "none",
+        confidence: 1.0,
+        probabilities: {},
+        clarificationNeeded: false,
+        alternativeCandidates: [],
+      };
+    }
+
+    // Direct exact match fast-path (e.g. user literally typed "e4" or "Nf3")
+    const exactMatch = candidates.find(
+      (m) =>
+        m.san.toLowerCase() === userQuery.trim().toLowerCase() ||
+        `${m.from}${m.to}`.toLowerCase() === userQuery.trim().toLowerCase()
+    );
+    if (exactMatch) {
+      return {
+        query: userQuery,
+        matchedMove: exactMatch,
+        san: exactMatch.san,
+        confidence: 1.0,
+        probabilities: { [exactMatch.san]: 1.0 },
+        clarificationNeeded: false,
+        alternativeCandidates: [],
+      };
+    }
+
+    // Build Choice criteria from legal moves
+    const criteria: Record<string, string> = {};
+    for (const c of candidates) {
+      criteria[c.san] = c.description;
+    }
+    criteria["none"] = "No legal candidate move matches what the player requested";
+
+    const state = {
+      user_intent: userQuery,
+      board: {
+        turn: engine.turn(),
+        in_check: engine.isCheck(),
+        fen: engine.fen(),
+      },
+      legal_moves: candidates.map((c) => ({
+        san: c.san,
+        description: c.description,
+      })),
+    };
+
+    const response = await this.client.systemOne({
+      state,
+      questions: {
+        matched_move: choice(
+          "Which legal chess move in `legal_moves` best fulfills the player's command in `user_intent`?",
+          criteria
+        ),
+      },
+    });
+
+    const answer = response.answers.matched_move;
+    const selectedSan = answer.choice;
+    const confidence = answer.confidence;
+    const probabilities = answer.probabilities as Record<string, number>;
+
+    // Sort alternatives by probability
+    const sortedOptions = Object.entries(probabilities)
+      .filter(([k]) => k !== "none" && k !== selectedSan)
+      .sort((a, b) => b[1] - a[1])
+      .map(([k]) => k);
+
+    if (selectedSan === "none" || confidence < confidenceThreshold) {
+      return {
+        query: userQuery,
+        matchedMove: null,
+        san: selectedSan,
+        confidence,
+        probabilities,
+        clarificationNeeded: true,
+        alternativeCandidates: sortedOptions.slice(0, 3),
+      };
+    }
+
+    const matched = candidates.find((c) => c.san === selectedSan) ?? null;
+
+    return {
+      query: userQuery,
+      matchedMove: matched,
+      san: selectedSan,
+      confidence,
+      probabilities,
+      clarificationNeeded: false,
+      alternativeCandidates: sortedOptions.slice(0, 2),
+    };
+  }
+}

package/src/personaEngine.ts

@@ -0,0 +1,193 @@
+import type { ChessEngine } from "./chessEngine.js";
+import { getTypeSafeClient, noul, score } from "./typeSafeClient.js";
+import type {
+  AnnotatedMove,
+  DimensionScores,
+  PersonaDecision,
+  PersonaId,
+  PersonaProfile,
+  PersonaScoredMove,
+} from "./types.js";
+
+export const CHESS_PERSONAS: Record<PersonaId, PersonaProfile> = {
+  tal: {
+    id: "tal",
+    name: "Mikhail Tal",
+    title: "The Magician from Riga",
+    quote:
+      "You must take your opponent into a deep dark forest where 2+2=5, and the path leading out is only wide enough for one.",
+    weights: {
+      aggression: 0.45,
+      prophylaxis: -0.15,
+      complexity: 0.5,
+      materialGreed: -0.2,
+    },
+  },
+  petrosian: {
+    id: "petrosian",
+    name: "Tigran Petrosian",
+    title: "Iron Tigran",
+    quote: "Nothing can be done against me; my position is so solid.",
+    weights: {
+      aggression: 0.05,
+      prophylaxis: 0.65,
+      complexity: -0.3,
+      materialGreed: 0.2,
+    },
+  },
+  capablanca: {
+    id: "capablanca",
+    name: "José Raúl Capablanca",
+    title: "The Chess Machine",
+    quote:
+      "A master plays simple chess, puts pieces where they belong, and simplifies into a clean endgame.",
+    weights: {
+      aggression: 0.2,
+      prophylaxis: 0.35,
+      complexity: -0.4,
+      materialGreed: 0.45,
+    },
+  },
+  coffeehouse: {
+    id: "coffeehouse",
+    name: "Coffeehouse Gambiteer",
+    title: "Romantic Hustler",
+    quote: "Checks are free, pawn storms are mandatory, and danger lurks on every rank.",
+    weights: {
+      aggression: 0.55,
+      prophylaxis: -0.35,
+      complexity: 0.4,
+      materialGreed: -0.1,
+    },
+  },
+};
+
+const AGGRESSION_RUBRIC = [
+  "Passive retreat, backward consolidation, or defensive block",
+  "Neutral developing maneuver or quiet regrouping",
+  "Forward thrust, central pressure, or active threat creation",
+  "Direct sacrifice, attack on the king, or fierce tactical challenge",
+] as const;
+
+const PROPHYLAXIS_RUBRIC = [
+  "Completely ignores king safety and opponent counterplay",
+  "Standard move with ordinary tactical exposure",
+  "Solid, patient reinforcement of weaknesses or squares",
+  "Deep prophylactic suppression of opponent counter-ideas",
+] as const;
+
+const COMPLEXITY_RUBRIC = [
+  "Clarifies position, forces trades, or liquidates tension",
+  "Steady, orderly position with clear structural goals",
+  "Introduces sharp asymmetry, unbalances, and multiple branches",
+  "Maximum chaos: highly volatile tactical minefield",
+] as const;
+
+/**
+ * AI Opponent decision engine powered by TypeSafe Composite Scoring.
+ * Pattern: Atomic Multi-Dimensional Scoring + Client-Side Persona Weights.
+ */
+export class PersonaEngine {
+  private get client() {
+    return getTypeSafeClient();
+  }
+
+  /**
+   * Scores candidate moves and selects the top move according to the persona's style.
+   */
+  public async selectMove(
+    engine: ChessEngine,
+    personaId: PersonaId,
+    candidateLimit = 5
+  ): Promise<PersonaDecision> {
+    const persona = CHESS_PERSONAS[personaId];
+    const allMoves = engine.getAnnotatedMoves();
+
+    if (allMoves.length === 0) {
+      throw new Error("No legal moves available in current position.");
+    }
+
+    // Candidate selection: curate a diverse pool representing varied styles
+    // (tactical strikes, prophylactic castle/pawn moves, central development)
+    const tacticalMoves = allMoves.filter((m) => m.isCheck || m.isCapture);
+    const quietMoves = allMoves.filter((m) => !m.isCheck && !m.isCapture);
+
+    const pool: AnnotatedMove[] = [];
+    if (tacticalMoves.length > 0) pool.push(...tacticalMoves.slice(0, 2));
+    if (quietMoves.length > 0) pool.push(...quietMoves.slice(0, Math.max(2, candidateLimit - pool.length)));
+
+    const candidates = pool.slice(0, candidateLimit);
+    const scoredCandidates: PersonaScoredMove[] = [];
+
+    // Evaluate each candidate move across atomic dimensions
+    for (const move of candidates) {
+      const state = {
+        candidate_move: {
+          san: move.san,
+          description: move.description,
+          is_capture: move.isCapture,
+          is_check: move.isCheck,
+        },
+        board: {
+          turn: engine.turn(),
+          fen: engine.fen(),
+          material: engine.getMaterialBalance().description,
+        },
+      };
+
+      const response = await this.client.systemOne({
+        state,
+        questions: {
+          aggression: score(
+            "How aggressive and attacking is `candidate_move.san`?",
+            AGGRESSION_RUBRIC
+          ),
+          prophylaxis: score(
+            "How well does `candidate_move.san` ensure safety and stifle opponent counterplay?",
+            PROPHYLAXIS_RUBRIC
+          ),
+          complexity: score(
+            "How much tactical tension and complexity does `candidate_move.san` inject into the board?",
+            COMPLEXITY_RUBRIC
+          ),
+          material_greed: noul(
+            "Is the move `candidate_move.san` primarily motivated by winning or defending material?"
+          ),
+        },
+      });
+
+      const dimScores: DimensionScores = {
+        aggression: response.answers.aggression.score,
+        prophylaxis: response.answers.prophylaxis.score,
+        complexity: response.answers.complexity.score,
+        materialGreed: response.answers.material_greed.noul,
+      };
+
+      // Composite scoring formula in code
+      const compositeScore =
+        persona.weights.aggression * dimScores.aggression +
+        persona.weights.prophylaxis * dimScores.prophylaxis +
+        persona.weights.complexity * dimScores.complexity +
+        persona.weights.materialGreed * dimScores.materialGreed;
+
+      scoredCandidates.push({
+        move,
+        compositeScore: Math.round(compositeScore * 1000) / 1000,
+        dimensionScores: dimScores,
+      });
+    }
+
+    // Sort by composite score descending
+    scoredCandidates.sort((a, b) => b.compositeScore - a.compositeScore);
+
+    const best = scoredCandidates[0]!;
+    const rationale = `${persona.name} (${persona.title}) selected ${best.move.san} with composite score ${best.compositeScore} (Aggression: ${best.dimensionScores.aggression.toFixed(1)}, Prophylaxis: ${best.dimensionScores.prophylaxis.toFixed(1)}, Complexity: ${best.dimensionScores.complexity.toFixed(1)}, Greed: ${best.dimensionScores.materialGreed.toFixed(2)}).`;
+
+    return {
+      persona,
+      selectedMove: best.move,
+      rankedCandidates: scoredCandidates,
+      rationale,
+    };
+  }
+}