fabioc-aloha/ChessCoach

Latest recorded source activity: May 5, 2026 at 20:58

SkillsMP catalog refreshed: November 12, 2026 at 12:52

skills collected: 280

GitHub stars: 1
GitHub forks: 0

Install with an AI assistant

Copy this prompt into the AI assistant you're using.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/fabioc-aloha/ChessCoach.

Repository README

Repository README source: README.md

Read the source README

Expand full README

<div align="center"> <img src="assets/banner.svg" alt="ChessCoach Banner" width="100%"> <br> </div> # ChessCoach ♟️ AI-powered chess coaching with **dual-engine analysis**: Stockfish for optimal moves + Maia-2 for human-like play prediction. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Deployed](https://img.shields.io/badge/Azure-Deployed-success)](https://chesscoach.correax.com) [![Backend](https://img.shields.io/badge/Backend-Container%20Apps-blue)](https://chesscoach-api.delightfulisland-4ff8b65a.eastus2.azurecontainerapps.io/docs) [![CorreaX](https://img.shields.io/badge/CorreaX-Product-0078d4)](https://correax.com) **🌐 Live Demo: [chesscoach.correax.com](https://chesscoach.correax.com/)** > **Production Status (February 2026)** > > - **Frontend**: [chesscoach.correax.com](https://chesscoach.correax.com) > - **Backend API**: [Azure Container Apps](https://chesscoach-api.delightfulisland-4ff8b65a.eastus2.azurecontainerapps.io) > - **API Docs**: [Swagger UI](https://chesscoach-api.delightfulisland-4ff8b65a.eastus2.azurecontainerapps.io/docs) > - **Tests**: 319 backend + 324 frontend (643 total) ## Infrastructure Control This is a hobby project - save costs by stopping infrastructure when not in use: ```powershell .\infra\manage-infra.ps1 status # Check current state & costs .\infra\manage-infra.ps1 stop # Stop everything (~$8/mo) .\infra\manage-infra.ps1 start # Start everything (~$59/mo) ``` | State | PostgreSQL | Container App | Est. Cost | |-------|------------|---------------|-----------| | **Running** | Ready | min=1 replica | ~$59/mo | | **Stopped** | Stopped | min=0 (scale-to-zero) | ~$8/mo | > **Note**: PostgreSQL auto-restarts after 7 days. Run `stop` again if needed. ## Features - **🎮 Play vs Stockfish** - 4 difficulty levels + continue from any position (great for opening practice!) - **🤖 Stockfish Opponent** - Challenge the engine, just say "play against Stockfish" or use the UI - **🔮 Dual-Engine Analysis** - Stockfish optimal moves + Maia-2 human-like predictions (any ELO 800-2800) - **📊 ELO Estimation** - Estimate your playing strength based on move alignment with Maia-2 - **📖 Opening Library** - Browse and learn 80+ chess openings with step-by-step animation - **🧩 Puzzle Mode** - 5.6M+ tactical puzzles from Lichess with rating/theme filters - **📰 Chess News** - Live broadcasts, top games, streamers, and articles from Lichess - **🧠 Coach Alex** - AI coaching with 7 personalities (Encouraging, Analytical, Casual, Strict, Socratic, Pirate 🏴‍☠️, Santa 🎅) - **💬 Ask Anything** - Chat with Coach Alex about any position using 43 specialized tools - **➡️ Smart Arrows** - Green when engines agree, Purple (Stockfish) + Blue (Maia) when they differ - **🎨 Customizable UI** - 5 board themes, 11 piece styles, dark/light/system color schemes - **📝 Chat History** - Analysis outputs accumulate like a conversation - **🏢 CorreaX Branding** - Professional company attribution with reusable footer components ## Quick Start ```powershell # Clone and enter project git clone https://github.com/fabioc-aloha/chesscoach.git cd ChessCoach # Start both servers (opens browser automatically) .\start-dev.ps1 ``` **Prerequisites**: Python 3.11+, Node.js 18+, [Stockfish](https://stockfishchess.org/download/) ## First-Time Setup ```powershell # Backend cd backend python -m venv .venv .venv\Scripts\activate pip install -r requirements.txt # Frontend cd ../frontend npm install # Optional: Azure OpenAI for Coach Alex cd ../backend copy .env.example .env # Edit .env with your Azure OpenAI credentials ``` ## Tech Stack | Layer | Technology | | --- | --- | | **Backend** | FastAPI, python-chess, Pydantic, Uvicorn, asyncpg | | **Frontend** | React 19, TypeScript, Vite 6, chess.js, react-chessboard | | **Chess Engines** | Stockfish (optimal), Maia-2 (human-like, any ELO 800-2800) | | **AI Coaching** | Azure AI Foundry (Model Router - auto-selects GPT-4o, GPT-5, Claude, etc.) | | **Database** | Azure PostgreSQL (5.6M+ Lichess puzzles) | | **Infrastructure** | Azure Container Apps (Backend), Static Web Apps (Frontend), ACR | | **Testing** | Pytest (319 tests), Vitest (324 tests) | ## Architecture ```mermaid flowchart TB subgraph Frontend["Frontend (React + Vite)"] UI[Interactive Chessboard] Controls[Game Controls] Chat[Analysis Chat] Arrows[Smart Arrows Overlay] end subgraph Backend["Backend (FastAPI)"] API[REST API] Chess[Chess Logic] LLM[LLM Client] Dual[Dual Analysis] end subgraph Engines["Chess Engines"] Stockfish[("Stockfish\n(Optimal Play)")] Maia[("Maia-2\n(Human-like 800-2800)")] end subgraph External["External Services"] Azure[("Azure OpenAI")] end UI --> API Controls --> API Chat --> API API --> Chess API --> LLM API --> Dual Dual --> Stockfish Dual --> Maia Chess <--> Stockfish LLM <--> Azure Stockfish --> Arrows Maia --> Arrows style Frontend fill:#61dafb,color:#000 style Backend fill:#009688,color:#fff style Engines fill:#4caf50,color:#fff style External fill:#ff9800,color:#000 ``` ## Project Structure ```text ChessCoach/ ├── backend/ # FastAPI server + dual-engine integration │ ├── app/ │ │ ├── api/ # REST endpoints (analysis, dual-analyze, coaching, puzzles) │ │ ├── chess/ # Stockfish + Maia-2 clients │ │ ├── db/ # Database models and repositories (PostgreSQL) │ │ ├── llm/ # Azure OpenAI integration │ │ ├── news/ # Chess news aggregation (Lichess API + RSS feeds) │ │ ├── openings/ # Opening library service (80+ openings) │ │ └── puzzles/ # Puzzle service (5.6M+ Lichess puzzles) | └── tests/ # Pytest test suite (319 tests) ├── frontend/ # React + TypeScript UI │ └── src/ │ └── components/ # Chessboard, ChessArrows, DualAnalysisPanel, EloEstimation, etc. ├── engines/ # Stockfish binary (local dev only) ├── infra/ # Azure deployment (Bicep + PowerShell scripts) │ └── logs/ # Deployment logs (gitignored) ├── docs/ # Architecture and planning documentation │ └── archive/ # Completed/historical documents (CODE-REVIEW, MAIA-RESEARCH) └── domain-knowledge/ # AI cognitive architecture files ``` **Note:** Maia-2 is installed as a pip package (`pip install maia2`) - no binary setup needed. ## Coach Alex - Agentic AI Coach Alex uses an **agentic AI architecture** where the Azure AI Foundry Model Router autonomously calls **43 specialized tools** across **13 categories** to analyze positions, explain concepts, and control the game. The router automatically selects the optimal model (GPT-4o, GPT-5, Claude, etc.) for each request. ```mermaid flowchart TB subgraph Frontend UI[React Chess UI] Chat[Chat Component] end subgraph API["FastAPI Backend"] CoachEndpoint["/api/coaching/coach"] ChatEndpoint["/api/coaching/chat"] AzureClient[AzureOpenAIClient] ToolExecutor["AgentToolExecutor (43 tools)"] end subgraph Engines["Chess Engines"] Stockfish[(Stockfish)] Maia[(Maia-2)] end subgraph Cloud["Azure AI Foundry"] LLM[Model Router] end UI --> Chat Chat -->|POST /chat| ChatEndpoint ChatEndpoint --> AzureClient AzureClient <-->|Tool Calls| LLM AzureClient --> ToolExecutor ToolExecutor -->|12 blocking tools| Stockfish ToolExecutor -->|5 blocking tools| Maia ChatEndpoint -->|Response + Arrows + Actions| Chat ``` ### Tool Categories (43 tools, 13 categories) | Category | Tools | Description | | --- | --- | --- | | **Analysis** (7) | `analyze_position`, `compare_moves`, `get_threats`, `get_piece_info`, `get_legal_moves`, `get_position_features`, `analyze_specific_move` | Deep position analysis via Stockfish | | **Educational** (4) | `get_opening_name`, `get_game_phase`, `explain_tactic`, `find_checkmate` | Learn chess concepts and openings | | **Strategic** (4) | `get_pawn_structure`, `suggest_plan`, `get_king_safety`, `get_piece_activity` | Strategic planning and evaluation | | **Learning** (4) | `explain_why_bad`, `get_candidate_moves`, `calculate_line`, `get_endgame_type` | Understand mistakes and find moves | | **Maia-2** (4) | `get_human_move`, `get_human_top_moves`, `compare_skill_levels`, `get_win_probability` | Human-like predictions (800-2800 ELO) | | **Visualization** (4) | `highlight_squares`, `draw_arrows`, `show_attacked_squares`, `show_piece_influence` | Board highlighting and arrows | | **Move Execution** (3) | `make_move`, `undo_move`, `play_variation` | Execute and demonstrate moves | | **Navigation** (2) | `get_move_history`, `setup_position` | Navigate game history | | **Training** (3) | `setup_puzzle`, `check_user_move`, `give_hint` | Interactive puzzle training | | **Advanced Analysis** (4) | `find_outposts`, `analyze_pawn_breaks`, `find_tricky_moves`, `get_space_advantage` | Expert-level analysis | | **PGN** (2) | `load_pgn`, `export_pgn` | Import/export games | | **Game Control** (1) | `enable_stockfish_opponent` | Toggle Stockfish as opponent | | **Help** (1) | `get_help` | Explain capabilities | ### Architecture Highlights - **Async Tool Execution**: 17 blocking tools (Stockfish/Maia) run in thread pools to avoid blocking the FastAPI event loop - **Multi-Turn Reasoning**: Up to 10 tool call iterations per request for complex analysis - **Smart Arrow Generation**: Tools return `suggested_moves` that render as arrows on the board - **Action System**: Tools can trigger frontend actions (e.g., flip board when enabling Stockfish opponent) - **Context-Aware**: All tools receive current FEN, move history, and game state See [docs/architecture/AGENTIC-AI-ARCHITECTURE.md](docs/architecture/AGENTIC-AI-ARCHITECTURE.md) for complete tool definitions and request flow diagrams. ## Dual-Engine Analysis ChessCoach uniquely combines two perspectives: - **Stockfish** - World's strongest engine, shows the objectively best move - **Maia-2** - Neural network predicting human moves at ANY skill level (800-2800 ELO, continuous) **Smart Arrows:** - 🟢 **Green arrow** - Both engines agree (optimal = human-intuitive) - 🟣 **Purple arrow (S)** - Stockfish's optimal move - 🔵 **Blue arrow (M)** - Maia-2's human-like prediction This helps you understand not just what's best, but *why* certain moves are more natural for humans. See [docs/architecture/AGENTIC-AI-ARCHITECTURE.md](docs/architecture/AGENTIC-AI-ARCHITECTURE.md) for details. ## Azure Deployment ChessCoach is deployed on Azure with a modern container-based architecture: | Component | Service | URL | | --- | --- | --- | | Frontend | Azure Static Web Apps | [chesscoach.correax.com](https://chesscoach.correax.com) | | Backend API | Azure Container Apps | [chesscoach-api.delightfulisland-4ff8b65a.eastus2.azurecontainerapps.io](https://chesscoach-api.delightfulisland-4ff8b65a.eastus2.azurecontainerapps.io) | | API Docs | Swagger UI | [/docs](https://chesscoach-api.delightfulisland-4ff8b65a.eastus2.azurecontainerapps.io/docs) | | Custom Domain | Azure DNS | [chesscoach.correax.com](https://chesscoach.correax.com) | ### Deploy Your Own ```powershell cd infra # Deploy infrastructure (OpenAI, PostgreSQL, Container Apps, Static Web App) .\deploy-infra.ps1 # Deploy backend to Container Apps (CPU-only, ~3 min build) .\deploy-backend.ps1 # Deploy frontend to Static Web Apps .\deploy-frontend.ps1 # Or deploy everything at once .\deploy-all.ps1 ``` **Deployment Optimizations:** - **CPU-only PyTorch** (~200MB) - Optimized for Azure Container Apps - **Pre-baked Maia-2** - `rapid_model.pt` (267MB) included in Docker image, no cold-start download - **Build time**: ~3 minutes in ACR - **Image size**: ~800MB - **Health checks**: Automatic validation with rollback support See [infra/README.md](infra/README.md) for detailed deployment options. ## Development See [docs/development/GETTING-STARTED.md](docs/development/GETTING-STARTED.md) for detailed setup. See [docs/development/V2-TASK-TRACKING.md](docs/development/V2-TASK-TRACKING.md) for roadmap and implementation tasks. See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines. ## License MIT License - see [LICENSE](LICENSE) for details.

Loading the repository README…

Skills in this repository

Software Developers

2026-05-05

brain-upgrade

Software Developers

Two-phase brain upgrade — mechanical install via shared core, then LLM-led semantic reconciliation

2026-05-05

brand-asset-management

Graphic Designers

Brand hierarchy, visual identity, asset deployment, platform-specific branding guidelines

2026-05-05

business-analysis

Project Management Specialists

Patterns for requirements elicitation, BRDs, process analysis, and stakeholder alignment.

2026-05-05

career-development

Human Resources Specialists

Resume crafting, interview preparation, job search strategy, and professional growth planning.

2026-05-05

Showing 40 of 280 collected skills.