Update README.md

README.md

@@ -1,3 +1,107 @@
----
-license: mit
----
+---
+license: cc-by-nc-4.0
+library_name: onnx
+tags:
+- chess
+- deep-learning
+- pytorch
+- onnx
+- resnet
+- strategy
+- game-ai
+- gambitflow
+datasets:
+- Rafs-an09002/gambitflow-elite-data
+language:
+- en
+pipeline_tag: reinforcement-learning
+metrics:
+- mse
+---
+
+# ♟️ GambitFlow Nexus-core (CE)
+
+<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%20CE&fontSize=50&animation=fadeIn&fontAlignY=35&desc=Elite%20ResNet%20Chess%20Intelligence&descAlignY=60)
+
+[![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/)
+![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)
+
+[**Live Engine Demo**](https://chessmate-engine.onrender.com/) • [**GitHub Repository**](https://github.com/NeuraxLabs/GambitFlow)
+
+</div>
+
+## 📖 Model Overview
+
+**Nexus-core CE** is the flagship chess engine of the **GambitFlow** project. It is a deep neural network designed to evaluate chess positions with grandmaster-like intuition. unlike traditional engines (like early Stockfish versions) that rely on hand-crafted evaluation functions, Nexus-core learned chess strategy by analyzing millions of games played by elite human players.
+
+It serves as the static evaluation function (brain) for the GambitFlow search algorithm.
+
+## 🧠 Technical Architecture
+
+The model is built using a **Residual Neural Network (ResNet)** architecture, inspired by AlphaZero but optimized for web deployment.
+
+| Component | Specification | Description |
+| :--- | :--- | :--- |
+| **Input Layer** | `(1, 12, 8, 8)` | A 12-channel bitboard representation. Channels 0-5 for White pieces, 6-11 for Black pieces. |
+| **Convolutional Block** | 128 Filters, 3x3 Kernel | Initial feature extraction from the raw board state. |
+| **Residual Tower** | **10 Blocks** | A stack of 10 Residual Blocks. Each block consists of `Conv2d -> BatchNorm -> ReLU -> Conv2d -> BatchNorm -> Add -> ReLU`. This depth allows the model to understand complex spatial patterns and long-term strategy. |
+| **Value Head** | Dense / Linear | Compresses the extracted features into a single scalar value. |
+| **Output** | `Scalar (-1.0 to 1.0)` | `Tanh` activated score. Positive values favor White, negative values favor Black. |
+| **Parameter Count** | **~3.5 Million** | Optimized for balancing depth and inference speed in browsers. |
+
+## 📊 Training Methodology
+
+The model was trained using a highly optimized pipeline on Google Colab (T4 GPUs).
+
+### 1. Data Source ("The Elite Dataset")
+We did not use random chess games. We curated a dataset (`gambitflow-elite-data`) specifically for high-level play.
+- **Source:** Lichess Standard Rated Games (January 2017).
+- **Filtering Criteria:** Both White and Black players must have an **ELO > 2000**.
+- **Volume:** Over **5,000,000 unique positions** extracted from the first 20 moves of elite games.
+
+### 2. Training Protocol
+- **Framework:** PyTorch 2.5.1.
+- **Optimization:**
+    - **Mixed Precision (AMP):** Used `torch.amp.autocast` (float16) to double the batch size and training speed without losing accuracy.
+    - **Optimizer:** AdamW with Weight Decay.
+    - **Loss Function:** Mean Squared Error (MSE) comparing the model's evaluation against the actual game outcome (0, 0.5, or 1).
+    - **Gradient Accumulation:** Effective batch size of 1024 to ensure stable convergence.
+
+### 3. Export & Optimization
+- The model was exported to **ONNX** format using **Opset Version 17**.
+- **Constant Folding** was enabled to bake static parts of the graph into the model, reducing runtime overhead.
+- Validated for **WebAssembly (WASM)** compatibility via `onnxruntime-web`.
+
+## 💻 Usage (JavaScript / ONNX Runtime)
+
+This model is designed to run client-side.
+
+```javascript
+import * as ort from 'onnxruntime-web';
+
+// 1. Initialize Session
+const session = await ort.InferenceSession.create('./chess_model_v2.onnx');
+
+// 2. Encode Board (FEN to Tensor)
+// Input must be a Float32Array of size 768 (12x8x8 flattened)
+const inputTensor = new ort.Tensor('float32', float32Array, [1, 12, 8, 8]);
+
+// 3. Run Inference
+const results = await session.run({ board_state: inputTensor });
+const evaluation = results.evaluation.data[0];
+
+console.log("Position Score:", evaluation);
+```
+
+## ⚠️ License
+
+**GambitFlow Nexus-core** is licensed under the **Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0)** license.
+
+- **Allowed:** Personal use, educational research, forking for non-commercial improvements.
+- **Prohibited:** Selling the model, using it in paid software services, or claiming it as your own without attribution.
+
+---