GUI_SETUP.md

Chess Master GUI - Setup & Launch

Quick Start

1. Set Gemini API Key

# Windows (PowerShell)
$env:GEMINI_API_KEY = "your_api_key_here"

# Windows (Command Prompt)
set GEMINI_API_KEY=your_api_key_here

# Linux/Mac
export GEMINI_API_KEY=your_api_key_here

Get a free key: https://aistudio.google.com/app/apikey

2. Run the GUI

Windows:

run_gui.bat

Linux/Mac:

bash run_gui.sh

Or manually:

python app.py

3. Open in Browser

http://localhost:5000

What's Included

Files

• app.py - Flask server with WebSocket support
• templates/index.html - Game UI
• static/style.css - Styling
• static/game.js - Client-side logic
• requirements-gui.txt - Python dependencies
• run_gui.bat / run_gui.sh - Quick start scripts

Features

✓ Modern, responsive web interface
✓ Chess board with legal move highlighting
✓ Real-time chat sidebar
✓ Agent responds naturally (chooses when to speak)
✓ Game statistics (moves, duration, messages)
✓ Player persistence (remembers you)
✓ Full trigger system (BEFORE_MATCH, ON_USER_MOVE, etc.)

How It Works

Game Flow

1. Start → Enter name → Click "Start Game"
2. BEFORE_MATCH trigger → Agent greets you (if it chooses to speak)
3. Make moves → Type or click legal moves
4. ON_USER_MOVE trigger → Agent responds (if interesting)
5. Agent moves → Random legal move (automated)
6. Repeat → Until game ends
7. AFTER_MATCH trigger → Agent reflects on game

Natural Conversation

The agent will:

• Speak when:

  • You make an interesting move
  • There's a critical moment (check, threat)
  • You ask a question in chat
  • Something unusual happens

• Stay silent when:

  • Routine opening moves
  • Nothing interesting to add
  • You're just thinking

This is controlled by the system prompt which encourages the agent to use "action": "stop" for silence.

Architecture

Backend

• Flask - Web server
• Flask-SocketIO - Real-time WebSocket communication
• GameSession - Per-client game state management
• Agent System - Full Chess Master with triggers

Frontend

• HTML5 - Semantic markup
• CSS3 - Modern styling with flexbox
• JavaScript - WebSocket client, game logic
• Socket.IO - Real-time communication

Async Flow

Client                    Server                      Agent
  |                         |                           |
  |--send move----------->  |                           |
  |                         |--trigger(ON_USER_MOVE)->  |
  |                         |                      [respond]
  |                         |<--response------------|
  |<--move_made------------|
  |                    [agent moves]
  |<--board update--------|
  |
  |--send message------->  |
  |                         |--trigger(ON_USER_INPUT)->|
  |                         |                     [respond]
  |                         |<--response------------|
  |<--message sent---------|

Troubleshooting

Port Already in Use

# Change port in app.py
socketio.run(app, debug=True, host="0.0.0.0", port=5001)  # Use 5001 instead

API Key Issues

• Verify key is set: echo %GEMINI_API_KEY% (Windows) or echo $GEMINI_API_KEY% (Unix)
• Get new key: https://aistudio.google.com/app/apikey
• Key should start with AIzaSy...

WebSocket Connection Failed

• Check browser console (F12 → Console)
• Ensure server is running: http://localhost:5000
• Check firewall settings

Customization

Change Port

Edit app.py:

socketio.run(app, debug=True, host="0.0.0.0", port=YOUR_PORT)

Change UI Colors

Edit static/style.css:

/* Primary color */
#1e3c72  /* Dark blue */
#2a5298  /* Light blue */
#6a1b9a  /* Agent purple */

Agent Personality

Edit agent/main_agent.py system prompt:

system_prompt = f"""You are Viktor Petrov...

Performance Notes

• Single player per session - Game state is per WebSocket connection
• No database persistence - Chat/moves only persist during game
• Random moves - Agent doesn't evaluate position (not a real chess engine)
• Threading async - WebSocket runs on thread pool

For production, consider:

• Redis for session management
• Database for move history
• Real chess engine for moves
• Authentication system

Next Steps

1. Play a full game and check agent responses
2. Test natural conversation (agent staying silent)
3. Play multiple games - agent should remember you
4. (Optional) Implement real chess AI for better moves

---

Ready to play?

python app.py

Then open: http://localhost:5000