Update README.md

README.md

@@ -17,6 +17,9 @@ language:
 pipeline_tag: reinforcement-learning
 metrics:
 - mse
+model-index:
+- name: GambitFlow Nexus-core (CE)
+  results: []
 ---
 
 # ♟️ GambitFlow Nexus-core (CE)
@@ -29,82 +32,80 @@ metrics:
 ![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://chessmate-engine.onrender.com/) • [**GitHub Repository**](https://github.com/NeuraxLabs/GambitFlow)
+[**Live Engine Demo**](https://chessmate-engine.onrender.com/) • [**Dataset Card**](https://huggingface.co/datasets/Rafs-an09002/gambitflow-elite-data)
 
 </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.
+**Nexus-core CE** (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 (brain) for the GambitFlow search algorithm.
+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 AlphaZero but optimized for web deployment.
+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)` | 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. |
+| **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
 
-The model was trained using a highly optimized pipeline on Google Colab (T4 GPUs).
+Nexus-core was trained using a professional-grade pipeline designed for robustness and strategic depth.
 
-### 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.
+### 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
-- **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.
+- **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. 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`.
+### 3. ONNX Optimization
+- Exported with **Opset 17**.
+- **Constant Folding** and Graph Optimization enabled to reduce latency during real-time play.
 
-## 💻 Usage (JavaScript / ONNX Runtime)
+## 💻 Implementation (JavaScript)
 
-This model is designed to run client-side.
+Designed for seamless integration with `onnxruntime-web`.
 
 ```javascript
 import * as ort from 'onnxruntime-web';
 
-// 1. Initialize Session
+// 1. Load the Brain
 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]);
+// 2. Prepare 12x8x8 Tensor (Encoded from FEN)
+const inputTensor = new ort.Tensor('float32', boardData, [1, 12, 8, 8]);
 
-// 3. Run Inference
+// 3. Get Evaluation
 const results = await session.run({ board_state: inputTensor });
-const evaluation = results.evaluation.data[0];
+const score = results.evaluation.data[0];
 
-console.log("Position Score:", evaluation);
+console.log("Nexus-core Evaluation:", score);
 ```
 
-## ⚠️ License
+## 🛡️ License & Ethics
 
-**GambitFlow Nexus-core** is licensed under the **Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0)** license.
+This model is shared 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.
+- **Attribution:** You must give credit to the GambitFlow project.
+- **Non-Commercial:** This model cannot be used for commercial purposes without an explicit agreement.
+- **Innovation:** We encourage researchers to fork and improve this model for non-commercial game-AI research.
 
 ---
 <div align="center">
-  <p>Curated by <a href="https://github.com/GambitFlow">GambitFlow</a></p>
+  <p>Developed by <a href="https://huggingface.co/Rafs-an09002">Rafsan</a> @ GambitFlow Labs</p>
 </div>