Feature/llm stockfish integration

.gitignore

@@ -13,6 +13,7 @@ node_modules
 #environment
 react-ystemandchess/environment.prod.ts
 react-ystemandchess/environment.ts
+react-ystemandchess/src/core/environments/
 environment.php
 .env
 environment.*.local

README.md

@@ -254,13 +254,32 @@ This project has been recently modularized for better organization and maintaina
 
 ## Docker Deployment
 
+### Full Platform Deployment
+
 To run all services using Docker:
 
 ```bash
 cd config
 docker-compose up
 ```
 
+### AI Tutor Feature (Standalone)
+
+To run just the AI Tutor feature with Docker:
+
+```bash
+docker-compose -f docker-compose.aitutor.yml up --build
+```
+
+This starts:
+- **React Frontend** on http://localhost:3001
+- **Chess Server API** on http://localhost:3000
+- **Stockfish Engine** on http://localhost:8080
+
+**✅ ARM64 (Apple Silicon) Support:** The AI Tutor now uses Stockfish 15.1 from Debian repositories, providing native ARM64 support with real-time analysis performance (1-2 seconds per move at depth 12).
+
+See [STOCKFISH_ARM64_SUCCESS.md](STOCKFISH_ARM64_SUCCESS.md) for detailed ARM64 setup and test results, or [DOCKER_SETUP.md](DOCKER_SETUP.md) for general Docker documentation.
+
 ---
 
 You're all set! Happy coding and thank you for contributing to educational equity! 🎯♟️

chessServer/Dockerfile

@@ -1,13 +1,18 @@
-FROM node
+FROM node:18.20.8
 
 WORKDIR /usr/src/app
 
+# Copy package files
 COPY package*.json ./
 
-RUN npm install
+# Install dependencies
 RUN npm ci --only=production
 
+# Copy source code
 COPY . .
 
+# Expose port
 EXPOSE 3000
-CMD [ "node", "index.js" ]
+
+# Start the server
+CMD [ "node", "src/index.js" ]

chessServer/env-example

@@ -0,0 +1,50 @@
+# Chess Server Environment Variables
+# Copy this file to .env and fill in your values
+#
+# For Docker: cp env-example .env && edit .env
+# For Local:  cp env-example .env && edit .env
+
+# =============================================================================
+# OpenAI Configuration
+# =============================================================================
+
+# Your OpenAI API key (required for real AI responses)
+# Get one at: https://platform.openai.com/api-keys
+OPENAI_API_KEY= <your-openai-api-key-here>
+
+# LLM Mode: "openai" or "mock"
+# - "openai": Uses real OpenAI API (requires valid OPENAI_API_KEY)
+# - "mock": Uses sample responses for testing (no API key needed)
+LLM_MODE=openai
+
+# OpenAI Model to use
+OPENAI_MODEL=gpt-4o
+
+# Timeout for OpenAI requests (milliseconds)
+OPENAI_TIMEOUT_MS=7000
+
+# Max retries for failed OpenAI requests
+OPENAI_MAX_RETRIES=0
+
+# Rate limit (requests per minute)
+OPENAI_RATE_LIMIT_RPM=60
+
+# =============================================================================
+# Stockfish Server Configuration
+# =============================================================================
+
+# For Docker deployment (use internal Docker network):
+STOCKFISH_SERVER_URL=http://stockfish-server:8080
+
+# For local development (uncomment this, comment out the above):
+# STOCKFISH_SERVER_URL=http://localhost:4002
+
+# =============================================================================
+# Server Configuration
+# =============================================================================
+
+# Server port
+PORT=3000
+
+# Enable metrics logging
+METRICS_LOG_ENABLED=true

chessServer/jest.config.js

@@ -1,4 +1,10 @@
 module.exports = {
-    testEnvironment: 'node'
-  };
-
+  testEnvironment: 'node',
+  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
+  // Suppress verbose output
+  verbose: false,
+  // Only show output for failed tests
+  silent: false,
+  // Suppress console output (handled in setup file)
+  testMatch: ['**/__tests__/**/*.js', '**/?(*.)+(spec|test).js']
+};

chessServer/jest.setup.js

@@ -0,0 +1,29 @@
+// Jest setup file to suppress verbose console logging during tests
+// Only errors and warnings will be shown
+
+// Check if verbose mode is enabled via environment variable
+const verboseMode = process.env.TEST_VERBOSE === 'true';
+
+if (!verboseMode) {
+    // Store original console methods
+    const originalLog = console.log;
+    const originalInfo = console.info;
+    const originalDebug = console.debug;
+
+    // Suppress console.log, console.info, and console.debug during tests
+    // This reduces noise while keeping error/warning visibility
+    console.log = jest.fn();
+    console.info = jest.fn();
+    console.debug = jest.fn();
+
+    // Keep console.error and console.warn visible for actual failures
+    // console.error and console.warn remain unchanged
+
+    // Restore original methods after all tests
+    afterAll(() => {
+        console.log = originalLog;
+        console.info = originalInfo;
+        console.debug = originalDebug;
+    });
+}
+

chessServer/package.json

@@ -5,7 +5,8 @@
   "main": "src/index.js",
   "scripts": {
     "start": "nodemon src/index.js",
-    "test": "jest --detectOpenHandles --forceExit"
+    "test": "jest --detectOpenHandles --forceExit",
+    "test:verbose": "TEST_VERBOSE=true jest --detectOpenHandles --forceExit --verbose"
   },
   "keywords": [],
   "author": "",
@@ -17,11 +18,12 @@
     "jest": "^29.7.0",
     "morgan": "^1.10.0",
     "nodemon": "^3.1.10",
+    "openai": "^6.15.0",
     "socket.io": "^4.7.5",
-    "socket.io-client": "^4.8.0",
+    "socket.io-client": "^4.7.5",
     "supertest": "^7.0.0"
   },
   "volta": {
     "node": "18.20.8"
   }
-}
+}