README.md

---
license: cc-by-nc-4.0
library_name: onnx
tags:
- chess
- deep-learning
- pytorch
- onnx
- strategy
- game-ai
- basic model
datasets:
- Rafs-an09002/chessmate-opening-stats
language:
- en
pipeline_tag: reinforcement-learning
---

# ♟️ ChessMate AI - CNN Evaluation Model

<div align="center">

![ChessMate Banner](https://capsule-render.vercel.app/api?type=waving&color=0:3498db,100:2c3e50&height=180&section=header&text=ChessMate%20Model&fontSize=50&animation=fadeIn&fontAlignY=35&desc=ONNX%20Chess%20Evaluation%20Network)

[![License: CC BY-NC 4.0](https://img.shields.io/badge/License-CC%20BY--NC%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-nc/4.0/)
![Format](https://img.shields.io/badge/Format-ONNX-blue)
![Input](https://img.shields.io/badge/Input-12x8x8%20Tensor-orange)

[**Live Demo**](https://chessmate-engine.onrender.com) • [**GitHub Repository**](https://github.com/Rafsan1711/Chessmate-Engine)

</div>

## 📖 Model Description

This is a **Convolutional Neural Network (CNN)** trained to evaluate chess positions. It takes a board state as input and outputs a scalar evaluation score between `-1` (Black winning) and `+1` (White winning).

It is the core "brain" of the **ChessMate AI** project, designed to run efficiently in web browsers using `onnxruntime-web`.

- **Architecture:** 3-Layer CNN with Batch Normalization and ReLU activation.
- **Framework:** Trained in PyTorch, exported to ONNX (Opset 14).
- **Size:** ~7.5 MB (Highly optimized for web loading).
- **Training Data:** 100,000+ Master-level games from Lichess (Standard Rated > 2000 ELO).

## 🛠️ Technical Specifications

### Input Shape
The model expects a Tensor of shape `(1, 12, 8, 8)` representing the board state using One-Hot Encoding.

- **Channels (12):**
  - 0-5: White Pieces (Pawn, Knight, Bishop, Rook, Queen, King)
  - 6-11: Black Pieces (Pawn, Knight, Bishop, Rook, Queen, King)
- **Dimensions (8x8):** The chess board squares.

### Output
- **Shape:** `(1, 1)`
- **Value:** Float between `-1.0` and `1.0`.
  - `> 0`: Advantage White
  - `< 0`: Advantage Black
  - `~ 0`: Equal/Draw

## 💻 Usage (JavaScript / ONNX.js)

This model is designed to be used directly in the browser via `onnxruntime-web`.

```javascript
import * as ort from 'onnxruntime-web';

// 1. Load the session
const session = await ort.InferenceSession.create('./chess_model.onnx');

// 2. Prepare Input (Float32Array of size 12*8*8)
// Convert FEN string to 12x8x8 one-hot encoded array
const inputData = new Float32Array(768).fill(0); 
// ... (Fill array based on piece positions) ...

const tensor = new ort.Tensor('float32', inputData, [1, 12, 8, 8]);

// 3. Run Inference
const results = await session.run({ board_state: tensor });
const evaluation = results.evaluation.data[0];

console.log(`Position Score: ${evaluation}`);
```

## 🧠 Training Details

- **Loss Function:** Mean Squared Error (MSE)
- **Optimizer:** Adam (lr=0.001)
- **Epochs:** 50 (with Early Stopping)
- **Target Label:** Normalized Stockfish Evaluation / Game Result (Win/Loss/Draw).

## ⚠️ License & Limitations

This model is licensed under **CC BY-NC 4.0** (Attribution-NonCommercial 4.0 International).

**You are free to:**
- Use this model for research, education, and personal projects.
- Modify and adapt the model.

**You may NOT:**
- Sell this model or use it in a commercial product without permission.

---

<div align="center">
  <p>Curated by <a href="https://github.com/GambitFlow">GambitFlow</a></p>
</div>
4