README.md

---
license: gpl-3.0
library_name: onnx
tags:
- chess
- deep-learning
- pytorch
- onnx
- resnet
- strategy
- game-ai
- gambitflow
- Chess engine
datasets:
- GambitFlow/Elite-Data
language:
- en
pipeline_tag: reinforcement-learning
metrics:
- mse
model-index:
- name: GambitFlow Nexus-core
  results: []
---

# ♟️ GambitFlow Nexus-core 

<div align="center">

![GambitFlow Banner](https://capsule-render.vercel.app/api?type=waving&color=0:8e44ad,100:2c3e50&height=200&section=header&text=Nexus-core%20&fontSize=50&animation=fadeIn&fontAlignY=35&desc=Elite%20ResNet%20Chess%20Intelligence&descAlignY=60)

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
![Architecture](https://img.shields.io/badge/Architecture-ResNet--10-orange)
![Parameters](https://img.shields.io/badge/Params-~3.5M-blue)
![Format](https://img.shields.io/badge/Format-ONNX%20(Opset%2017)-green)
![Type](https://img.shields.io/badge/Model--Type-Static--Evaluation-red)

[**Live Engine Demo**](https://gambitflow.onrender.com) • [**Dataset Card**](https://huggingface.co/datasets/Gambitflow/elite-data)

</div>

## 📖 Model Overview

**Nexus-core** (Core Edition) is the primary engine of the **GambitFlow** project. It is a deep Residual Neural Network designed to evaluate chess positions with high-level human-like intuition. Unlike traditional engines that use manual "if-then" logic, Nexus-core learned chess strategy by analyzing over **5 million positions** played by elite grandmaster-level players.

It serves as the static evaluation function (the "Brain") for the GambitFlow search algorithm, providing a numeric advantage score for any given board state.

## 🧠 Technical Architecture

The model is built using a **Residual Neural Network (ResNet)** architecture, inspired by the AlphaZero research but highly optimized for efficient inference in web browsers and low-power devices.

### Specification Table
| Component | Specification | Description |
| :--- | :--- | :--- |
| **Input Layer** | `(1, 12, 8, 8)` | 12-channel bitboard representation (6 for White, 6 for Black pieces). |
| **Convolutional Stem** | 128 Filters, 3x3 | Initial spatial feature extraction from the 8x8 grid. |
| **Residual Tower** | **10 Blocks** | A stack of 10 ResBlocks using Skip-Connections to prevent gradient vanishing and capture deep strategy. |
| **Value Head** | Dense / Tanh | Compresses 8192 high-level features into a single scalar evaluation. |
| **Output Range** | `[-1.0, 1.0]` | Positive favors White, negative favors Black. |
| **Params** | **~3.5 Million** | Balanced for high depth-to-speed ratio. |

## 📊 Training Methodology

Nexus-core was trained using a professional-grade pipeline designed for robustness and strategic depth.

### 1. The Elite Dataset
We utilized the `gambitflow-elite-data` corpus:
- **Filtering:** Only games where **both players had ELO > 2000**.
- **Stage:** Focused on the first 20 moves to master opening and middlegame transition.
- **Volume:** ~5,000,000 unique positions.

### 2. Training Protocol
- **Mixed Precision:** Trained using `torch.amp` (FP16) for 2x faster convergence and memory efficiency.
- **Optimizer:** AdamW with a weight decay of `1e-4` to prevent overfitting.
- **Loss:** MSE (Mean Squared Error) between the predicted value and the actual game result.

### 3. ONNX Optimization
- Exported with **Opset 17**.
- **Constant Folding** and Graph Optimization enabled to reduce latency during real-time play.

## 💻 Implementation (JavaScript)

Designed for seamless integration with `onnxruntime-web`.

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

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

// 2. Prepare 12x8x8 Tensor (Encoded from FEN)
const inputTensor = new ort.Tensor('float32', boardData, [1, 12, 8, 8]);

// 3. Get Evaluation
const results = await session.run({ board_state: inputTensor });
const score = results.evaluation.data[0];

console.log("Nexus-core Evaluation:", score);
```

## 🛡️ License & Ethics

This model is shared under the **GPL v3 (GNU General Public License Version 3)** license.



---
<div align="center">
  <p>Developed by <a href="https://huggingface.co/Rafs-an09002">Rafsan</a> @ GambitFlow</p>
</div>