ChessMentor AI

• 

• 

• 

• 

Inspiration

I've always loved chess, but I found that traditional engines (like Stockfish) are brilliant at calculating but terrible at explaining. They give you a number like "+1.5", but for a beginner or intermediate player, that number is meaningless without the "why." I wanted to build a tool that bridges the gap between raw calculation and human understanding. Instead of just telling you "Move Knight to f3," I wanted an AI coach that explains, "Moving the knight controls the center and prepares for castling, while keeping an eye on Black's weak pawn." This project was inspired by the desire to make high-level chess strategy accessible, interactive, and conversational.

What it does

ChessMentor AI is an interactive chess companion that combines a powerful Stockfish engine with the conversational intelligence of Google's Gemini models.

Real-time Analysis: As you play, the app evaluates the position instantly using a WebAssembly-based Stockfish engine running directly in the browser.

Conversational Coaching: You can ask Gemini questions like "Why is my position bad?" or "What's the plan here?" The AI analyzes the board state (FEN) and evaluation, then explains the strategy in plain English.

Visual Guidance: When the AI suggests a move, it doesn't just speak—it draws interactive arrows on the board to visualize the threat or opportunity.

Smart History: You can navigate back through your game history. The board updates instantly, and you can explore "what-if" scenarios without breaking your current game state.

Adaptive AI: It uses a multi-model fallback system (Gemma 3, Gemini 2.5 Flash) to ensure reliability and speed, switching automatically if one model hits rate limits.

How we built it

The project is a modern web application built with React and Vite.

Chess Logic: We used chess.js for move validation and game state management, and custom chessbaord interface.

Engine Integration: We integrated a WebAssembly (WASM) version of Stockfish. This runs in a dedicated web worker to ensure the UI remains buttery smooth even during deep calculations.

AI Backend: We utilized the Google Generative AI SDK. The core innovation is how we construct the prompt: we feed the AI the current FEN string, the engine's evaluation (e.g., +1.5), and the player's side. This grounds the LLM in the objective reality of the game while allowing it to generate human-like explanations.

Resilience: We implemented a robust fallback mechanism. The app attempts to use the high-quality Gemma 3 12B model first. If rate limits are hit, it seamlessly downgrades to Gemini 2.5 Flash or Flash-Lite, ensuring the user never faces a "service unavailable" error.

Challenges we ran into

State Synchronization: Keeping the React state (React components), the chess.js internal logic, and the Stockfish worker all in sync was tricky, especially when navigating through history. We had to ensure that clicking "Back" didn't reset the engine's calculation thread.

Rate Limits: While testing the cutting-edge Gemini 3 Preview models, we frequently hit the Requests Per Day (RPD) limits. This forced us to architect the Model Iteration System, which dynamically switches models upon failure. It turned a limitation into a robust feature!

Visualizing "The Mind": We wanted the user to feel when the AI was thinking. We created a custom SVG loader with a specific gradient spin that mimics the Gemini brand identity, giving users immediate visual feedback during API calls.

Accomplishments that we're proud of

The "Teacher" Persona: We successfully tuned the prompt to stop the AI from hallucinating illegal moves. By feeding it the engine's "Best Move" as a hint, we forced the LLM to explain correct chess theory rather than inventing its own rules.

Seamless Audio-Visuals: Integrating the move sounds and the dynamic arrow system (which draws custom SVG arrows based on coordinate geometry) makes the app feel polished and premium.

Zero-Backend: The entire app runs client-side (browser + API calls). There is no heavy server to maintain, making it scalable and fast.

What we learned

Prompt Engineering for Logic: We learned that LLMs are not chess engines. They are great at explaining chess but bad at calculating it. The best results come from a hybrid approach: let Stockfish do the math, and let Gemini do the talking.

Web Workers are Essential: Moving the heavy chess calculation to a background thread was crucial for performance. Without it, the UI would freeze every time the computer thought about a move.

What's next for ChessMentor AI

Voice Mode: Using the Gemini Live API, we want to add a real-time voice conversation mode so you can talk to your coach while playing, hands-free.

Personalized Training: We aim to add a database that tracks your common mistakes and uses Gemini to generate personalized puzzles based on your own weak spots.

Built With

• chess.js
• google-generative-ai
• react
• stockfish.js