Spaces:
Sleeping
Sleeping
| title: Nexus-Core Inference API | |
| emoji: ♟️ | |
| colorFrom: green | |
| colorTo: blue | |
| sdk: docker | |
| pinned: false | |
| license: gpl-3.0 | |
| # ♟️ Nexus-Core: Deep Search Chess Engine | |
|  | |
|  | |
|  | |
| **Nexus-Core** is a high-performance chess inference engine powered by a 13.2M parameter ResNet-20 neural network. It combines classical alpha-beta search with modern deep learning evaluation. | |
| --- | |
| ## 🎯 Model Details | |
| - **Architecture:** Pure CNN (ResNet-20 backbone) | |
| - **Parameters:** 13,242,433 | |
| - **Input:** 12-channel board representation | |
| - **Training Data:** 5M+ elite positions (2000+ ELO) | |
| - **Model Hub:** [GambitFlow/Nexus-Core](https://huggingface.co/GambitFlow/Nexus-Core) | |
| --- | |
| ## 🚀 Features | |
| ### Advanced Search Techniques | |
| - ✅ **Principal Variation Search (PVS)** - Enhanced alpha-beta with zero-window search | |
| - ✅ **Null Move Pruning** - Forward pruning for tactical positions | |
| - ✅ **Late Move Reductions (LMR)** - Adaptive depth reduction | |
| - ✅ **Quiescence Search** - Tactical sequence resolution | |
| - ✅ **Iterative Deepening** - Progressive depth increase with time management | |
| ### Move Ordering Enhancements | |
| - ✅ **Transposition Table** - Zobrist hashing with 128MB cache | |
| - ✅ **Killer Move Heuristic** - Beta cutoff tracking | |
| - ✅ **History Heuristic** - Move success statistics | |
| - ✅ **MVV-LVA** - Most Valuable Victim, Least Valuable Attacker | |
| - ✅ **Counter Move Table** - Refutation tracking | |
| ### Position Evaluation | |
| - ✅ **Neural Network** - 12-channel CNN evaluation | |
| - ✅ **Material Balance** - Classical piece values | |
| - ✅ **Endgame Detection** - Phase-specific adjustments | |
| - ✅ **King Safety** - Pawn shield and attack zones | |
| --- | |
| ## 📊 Performance Benchmarks | |
| | Metric | Value | | |
| |--------|-------| | |
| | **Average Move Time** | 1.5s @ depth 5 | | |
| | **Nodes per Second** | ~50,000 NPS | | |
| | **TT Hit Rate** | 65-75% | | |
| | **Est. Playing Strength** | 2000-2200 ELO | | |
| *Benchmarked on HF Spaces CPU (2 vCPU, 16GB RAM)* | |
| --- | |
| ## 📡 API Usage | |
| ### Endpoint: `POST /get-move` | |
| **Request:** | |
| ```json | |
| { | |
| "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1", | |
| "depth": 5, | |
| "time_limit": 3000 | |
| } | |
| ``` | |
| **Response:** | |
| ```json | |
| { | |
| "best_move": "e2e4", | |
| "evaluation": 0.32, | |
| "depth_searched": 5, | |
| "seldepth": 9, | |
| "nodes_evaluated": 75234, | |
| "time_taken": 1450, | |
| "nps": 51885, | |
| "pv": ["e2e4", "c7c5", "g1f3", "d7d6", "d2d4"], | |
| "tt_hit_rate": 68.5 | |
| } | |
| ``` | |
| ### Parameters | |
| | Parameter | Type | Range | Default | Description | | |
| |-----------|------|-------|---------|-------------| | |
| | `fen` | string | - | required | Position in FEN notation | | |
| | `depth` | int | 1-8 | 5 | Maximum search depth | | |
| | `time_limit` | int | 1000-15000 | 3000 | Time limit in milliseconds | | |
| --- | |
| ## 🏗️ Architecture | |
| ### Modular Design | |
| ``` | |
| nexus-core/ | |
| ├── app.py # FastAPI server | |
| ├── engine/ | |
| │ ├── __init__.py | |
| │ ├── search.py # PVS search algorithm | |
| │ ├── evaluate.py # Neural + classical evaluation | |
| │ ├── transposition.py # Zobrist TT with replacement | |
| │ ├── move_ordering.py # Multi-heuristic move ordering | |
| │ ├── time_manager.py # Adaptive time control | |
| │ └── endgame.py # Endgame detection | |
| └── models/ | |
| └── nexus_core.onnx # ONNX model (auto-downloaded) | |
| ``` | |
| ### Search Flow | |
| ``` | |
| Root Node (Iterative Deepening) | |
| ↓ | |
| Aspiration Window Search | |
| ↓ | |
| Principal Variation Search (PVS) | |
| ↓ | |
| Move Ordering (TT + Killer + History) | |
| ↓ | |
| Alpha-Beta with Pruning | |
| ↓ | |
| Quiescence Search (Captures/Checks) | |
| ↓ | |
| Neural Network Evaluation | |
| ``` | |
| --- | |
| ## 🔬 Research References | |
| This engine implements state-of-the-art techniques from: | |
| 1. **Alpha-Beta Pruning** | |
| - Knuth, D. E., & Moore, R. W. (1975). *An analysis of alpha-beta pruning*. Artificial Intelligence, 6(4), 293-326. | |
| 2. **Principal Variation Search** | |
| - Marsland, T. A. (1986). *A Review of Game-Tree Pruning*. ICCA Journal, 9(1), 3-19. | |
| 3. **Null Move Pruning** | |
| - Donninger, C. (1993). *Null Move and Deep Search: Selective-Search Heuristics for Obtuse Chess Programs*. ICCA Journal, 16(3), 137-143. | |
| 4. **Late Move Reductions** | |
| - Heinz, E. A. (2000). *Adaptive null-move pruning*. ICCA Journal, 23(3), 123-134. | |
| 5. **Transposition Tables** | |
| - Zobrist, A. L. (1970). *A New Hashing Method with Application for Game Playing*. Technical Report #88, Computer Sciences Department, University of Wisconsin, Madison, Wisconsin. | |
| 6. **Move Ordering (History Heuristic)** | |
| - Schaeffer, J. (1989). *The History Heuristic and Alpha-Beta Search Enhancements in Practice*. IEEE Transactions on Pattern Analysis and Machine Intelligence, 11(11), 1203-1212. | |
| 7. **Killer Move Heuristic** | |
| - Akl, S. G., & Newborn, M. M. (1977). *The principal continuation and the killer heuristic*. Proceedings of the 1977 annual conference, 466-473. | |
| 8. **Quiescence Search** | |
| - Harris, L. R. (1975). *The heuristic search under conditions of error*. Artificial Intelligence, 5(3), 217-234. | |
| 9. **Neural Network Evaluation** | |
| - Silver, D., et al. (2017). *Mastering Chess and Shogi by Self-Play with a General Reinforcement Learning Algorithm*. arXiv:1712.01815. | |
| 10. **Stockfish NNUE (Inspiration)** | |
| - Nasu, Y. (2018). *Efficiently Updatable Neural-Network-based Evaluation Functions for Computer Shogi*. The 28th World Computer Shogi Championship Appeal Document. | |
| --- | |
| ## ⚙️ System Requirements | |
| - **CPU:** 2+ cores recommended | |
| - **RAM:** 4GB minimum, 8GB recommended | |
| - **Storage:** 500MB for model + cache | |
| --- | |
| ## 🔧 Local Development | |
| ```bash | |
| # Clone the space | |
| git clone https://huggingface.co/spaces/GambitFlow/nexus-core-inference | |
| # Build Docker image | |
| docker build -t nexus-core . | |
| # Run locally | |
| docker run -p 7860:7860 nexus-core | |
| # Test API | |
| curl -X POST http://localhost:7860/get-move \ | |
| -H "Content-Type: application/json" \ | |
| -d '{"fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1", "depth": 5}' | |
| ``` | |
| --- | |
| ## 📈 Roadmap | |
| - [x] PVS search implementation | |
| - [x] Transposition table with Zobrist hashing | |
| - [x] Advanced move ordering (killer + history) | |
| - [x] Quiescence search | |
| - [ ] Syzygy tablebase integration | |
| - [ ] Multi-PV support | |
| - [ ] Opening book integration | |
| - [ ] Analysis mode with detailed statistics | |
| --- | |
| ## 🤝 Contributing | |
| This is part of the **GambitFlow** project. For issues or improvements, please contact the team. | |
| --- | |
| ## 📄 License | |
| This model is licensed under **GPL v3 (GNU General Public License Version 3)** | |
| --- | |
| ## 🙏 Acknowledgments | |
| - **Stockfish Team** - For pioneering chess engine research | |
| - **Leela Chess Zero** - For demonstrating neural network potential | |
| - **python-chess** - Excellent Python chess library | |
| - **ONNX Runtime** - Efficient cross-platform inference | |
| --- | |
| **Built with ❤️ by GambitFlow** | |
| *Making chess AI accessible to everyone* |