---
title: Nexus-Core Inference API
emoji: ♟️
colorFrom: green
colorTo: blue
sdk: docker
pinned: false
license: gpl-3.0
---

# ♟️ Nexus-Core: Deep Search Chess Engine

![Version](https://img.shields.io/badge/version-2.0.0-blue)
![Model Size](https://img.shields.io/badge/model-13.2M%20params-orange)
![Architecture](https://img.shields.io/badge/arch-ResNet--10-red)

**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*