Feature/llm stockfish integration

[MaydayBR]

Pull Request: Docker AI Tutor Implementation

Summary

This PR implements a fully dockerized AI Chess Tutor that analyzes chess moves using Stockfish and provides educational feedback via OpenAI GPT-4.

Key Features

• Real-time chess move analysis (< 1 second response time)
• AI-powered explanations of chess moves and positions
• Full Docker containerization for easy deployment
• Cross-platform support (Windows, Linux, macOS - both Intel and Apple Silicon)
• Optimized Stockfish integration with native ARM64 support
• Mock mode for development without API key
• Comprehensive test suite (133 tests, 100% pass rate)

---

Architecture

Services

┌─────────────────────────────────────────────────────────────────────────┐
│ aitutor-frontend (React + Nginx)                                        │
│ Port: 3001                                                              │
│ • User interface for chess game and AI tutor                           │
│ • Static files served by Nginx                                         │
└─────────────────────────────────────────────────────────────────────────┘
                              ↓ REST API
┌─────────────────────────────────────────────────────────────────────────┐
│ aitutor-backend (Node.js Chess Server)                                  │
│ Port: 3000                                                              │
│ • Move analysis endpoint (/api/analyze)                                │
│ • Question answering endpoint                                          │
│ • Orchestrates Stockfish + OpenAI                                      │
│ • Caching layer for responses                                          │
└─────────────────────────────────────────────────────────────────────────┘
                              ↓ HTTP
┌─────────────────────────────────────────────────────────────────────────┐
│ stockfish-server (Stockfish Chess Engine)                              │
│ Port: 8080                                                              │
│ • Position analysis with Stockfish 15.1                                │
│ • Native ARM64 and AMD64 support                                       │
│ • Fast analysis (200-400ms at depth 8)                                 │
└─────────────────────────────────────────────────────────────────────────┘

---

How to Run

Prerequisites

• Docker Desktop installed and running
• (Optional) OpenAI API key for real AI responses

Quick Start - Mock Mode (No API Key Needed)

1. Navigate to project root

   cd /path/to/Y_Stem_and_Chess/react

2. Start all services

   docker-compose -f docker-compose.aitutor.yml up --build

3. Access the application

   • Frontend: http://localhost:3001

4. Stop services

   docker-compose -f docker-compose.aitutor.yml down

Setup with Real OpenAI Integration

1. Create environment file

   cp chessServer/env-example chessServer/.env

2. Edit chessServer/.env with your API key

   IMPORTANT: Make sure these lines are NOT commented out (no # at start):

   OPENAI_API_KEY=sk-your-actual-api-key-here
   LLM_MODE=openai
   OPENAI_MODEL=gpt-4o

3. Start services

   docker-compose -f docker-compose.aitutor.yml up --build

4. Verify OpenAI mode is active
   Check logs for: [OpenAI] Running in OPENAI mode with model: gpt-4o

Detached Mode (Background)

# Start services in background
docker-compose -f docker-compose.aitutor.yml up -d

# View logs
docker-compose -f docker-compose.aitutor.yml logs -f

# Stop services
docker-compose -f docker-compose.aitutor.yml down

---

Testing

Quick Test Commands

# Stop Docker containers (required for full test suite)
docker-compose -f docker-compose.aitutor.yml down

# Run all tests (quiet mode - minimal logging)
cd chessServer
npm install
npm test

# Run tests with verbose output (for debugging)
npm run test:verbose

Expected Result: ✅ 133/133 tests pass in ~10 seconds

Step-by-Step Test Instructions

Step 1: Run Local Tests

# Ensure Docker containers are stopped
docker-compose -f docker-compose.aitutor.yml down

# Navigate to backend directory
cd chessServer

# Install dependencies (if not done)
npm install

# Run tests
npm test

Expected Output:

PASS src/tests/errorHandling.test.js
PASS src/tests/index.test.js
PASS src/tests/rateLimiter.test.js
PASS src/tests/api.test.js
PASS src/tests/server.test.js
PASS src/tests/openai.test.js
PASS src/tests/mockTutor.test.js
PASS src/tests/GameManager.test.js
PASS src/tests/AnalysisService.test.js
PASS src/tests/cache.test.js

Test Suites: 10 passed, 10 total
Tests:       133 passed, 133 total
Time:        ~10s

Step 2: Test Docker Build

# Return to project root
cd ..

# Build Docker images
docker-compose -f docker-compose.aitutor.yml build

Expected: All 3 images build successfully

Step 3: Test Docker Deployment

# Start all services
docker-compose -f docker-compose.aitutor.yml up -d

# Verify containers are running
docker ps

Expected Output:

NAMES              STATUS      PORTS
aitutor-frontend   Up          0.0.0.0:3001->80/tcp
aitutor-backend    Up          0.0.0.0:3000->3000/tcp
stockfish-server   Up          0.0.0.0:8080->8080/tcp

Step 4: Check Logs for Errors

docker-compose -f docker-compose.aitutor.yml logs

✅ Expected: No errors or critical warnings

Step 6: Clean Up

docker-compose -f docker-compose.aitutor.yml down

---

Cross-Platform Compatibility

Platform Support

• ✅ Windows AMD64 (via WSL2 or Docker Desktop)
• ✅ Linux AMD64 (Intel/AMD processors)
• ✅ macOS ARM64 (Apple Silicon M1/M2/M3)
• ✅ macOS AMD64 (Intel processors)

Docker Images

• node:18.20.8 (multi-arch) - Chess Server
• node:18.20.8-slim (multi-arch) - Stockfish Server
• nginx:alpine (multi-arch) - Frontend

Stockfish

• Installed via apt-get from Debian repositories
• Native binaries for both AMD64 and ARM64
• No emulation needed - runs natively on all platforms

---

Troubleshooting

Issue: Tests fail with port conflicts

Solution: Stop Docker containers before running tests

docker-compose -f docker-compose.aitutor.yml down
cd chessServer && npm test

Issue: "Cannot connect to Docker daemon"

Solution: Start Docker Desktop application

Issue: Frontend shows 404

Solution: Ensure you're accessing http://localhost:3001 (not 3000)

Issue: Stockfish timeout errors

Solution: Depth is already optimized at 8. Check if container is running:

docker logs stockfish-server

Issue: OpenAI not working (still in mock mode)

Solution: Check your .env file - ensure variables are NOT commented out:

• Remove # from start of OPENAI_API_KEY and LLM_MODE lines
• Set LLM_MODE=openai (not mock)

Issue: "Module not found" errors

Solution: Reinstall dependencies

cd chessServer && npm install

---

PR Review Checklist

For Reviewers - Complete This Checklist:

Prerequisites

• Docker Desktop is installed and running

Step 1: Clone and Test

• Checkout branch: git checkout feature/LLM_Stockfish_integration
• Stop Docker: docker-compose -f docker-compose.aitutor.yml down
• Run tests: cd chessServer && npm install && npm test
• Verify: 133/133 tests pass

Step 2: Docker Build

• Return to root: cd ..
• Build images: docker-compose -f docker-compose.aitutor.yml build
• Verify: All 3 images build without errors

Step 3: Deployment Test

• Start services: docker-compose -f docker-compose.aitutor.yml up -d
• Check containers: docker ps
• Verify: All 3 containers running

Step 4: Clean Up

• Stop services: docker-compose -f docker-compose.aitutor.yml down

---