README.md

---
title: Nexus-Core Inference API
emoji: ⚡
colorFrom: green
colorTo: blue
sdk: docker
pinned: false
license: cc-by-nc-4.0
---

# ⚡ Nexus-Core Inference API

Fast and efficient chess move prediction powered by Nexus-Core v2.0.

[![Model](https://img.shields.io/badge/Model-Nexus--Core-green)](https://huggingface.co/GambitFlow/Nexus-Core)
[![Parameters](https://img.shields.io/badge/Params-13M-orange)](https://huggingface.co/GambitFlow/Nexus-Core)
[![Speed](https://img.shields.io/badge/Speed-Ultra--Fast-brightgreen)](https://huggingface.co/GambitFlow/Nexus-Core)

## 🎯 Model Details

**Nexus-Core** is a lightweight ResNet-based chess engine optimized for speed:

- **Model:** [GambitFlow/Nexus-Core](https://huggingface.co/GambitFlow/Nexus-Core)
- **Parameters:** 13 Million
- **Architecture:** Pure CNN (ResNet with 10 blocks)
- **Input:** 12-channel board representation
- **Training Data:** [GambitFlow/Elite-Data](https://huggingface.co/datasets/GambitFlow/Elite-Data) (5M+ positions)
- **Strength:** 2000-2200 ELO estimated

## 🔬 Search Algorithm

Efficient alpha-beta implementation with essential optimizations:

### Core Features
- **Alpha-Beta Pruning** [^1] - Classic minimax with cutoffs
- **Iterative Deepening** [^2] - Progressive depth increase
- **Quiescence Search** [^3] - Tactical sequence resolution
- **Simple Transposition Table** - 100K position cache

### Move Ordering
- **MVV-LVA** [^4] - Most Valuable Victim - Least Valuable Attacker
- **Promotion prioritization**
- **Check detection**

## 📊 Performance

| Metric | Value | Environment |
|--------|-------|-------------|
| **Depth 4 Search** | ~0.5-1 second | HF Spaces CPU |
| **Average Nodes** | 5K-15K per move | Typical positions |
| **Memory Usage** | ~2GB RAM | Peak inference |
| **Response Time** | 500-1000ms | 95th percentile |

## 📡 API Endpoints

### `POST /get-move`

**Request:**
```json
{
  "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
  "depth": 4,
  "time_limit": 3000
}
```

**Response:**
```json
{
  "best_move": "e2e4",
  "evaluation": 0.21,
  "depth_searched": 4,
  "nodes_evaluated": 8432,
  "time_taken": 856
}
```

### `GET /health`

Health check endpoint.

## 🔧 Parameters

- **fen** (required): Board position in FEN notation
- **depth** (optional): Search depth (1-6, default: 4)
- **time_limit** (optional): Max time in milliseconds (1000-10000, default: 3000)

## 🚀 Quick Start

```python
import requests

response = requests.post(
    "https://YOUR-SPACE.hf.space/get-move",
    json={
        "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
        "depth": 4
    }
)

data = response.json()
print(f"Best move: {data['best_move']}")
print(f"Evaluation: {data['evaluation']}")
```

## 💻 Use Cases

Perfect for:
- **Online chess platforms** - Fast response times
- **Training applications** - Consistent ~2000 ELO play
- **Mobile apps** - Lightweight inference
- **Rapid/Blitz games** - Quick move generation

## 📚 Research References

[^1]: **Alpha-Beta Pruning**: Knuth, D. E., & Moore, R. W. (1975). "An analysis of alpha-beta pruning". *Artificial Intelligence*, 6(4), 293-326.

[^2]: **Iterative Deepening**: Korf, R. E. (1985). "Depth-first iterative-deepening: An optimal admissible tree search". *Artificial Intelligence*, 27(1), 97-109.

[^3]: **Quiescence Search**: Shannon, C. E. (1950). "Programming a computer for playing chess". *Philosophical Magazine*, 41(314), 256-275.

[^4]: **MVV-LVA**: Hyatt, R. M., Gower, A. E., & Nelson, H. L. (1990). "Cray Blitz". *Computers, Chess, and Cognition*, 111-130.

## 📖 Related Work

- **Stockfish**: https://stockfishchess.org/ - Open-source chess engine
- **Fruit**: Letouzey, F. (2005). "Fruit 2.1 source code". http://www.fruitchess.com/
- **Crafty**: Hyatt, R. M. (1996-2023). "Crafty Chess Program". https://www.craftychess.com/

## 🏆 Model Lineage

**GambitFlow AI Engine Series:**
1. Nexus-Nano (2.8M) - Ultra-fast baseline
2. **Nexus-Core (13M)** - Balanced performance ✨
3. Synapse-Base (38.1M) - State-of-the-art

## ⚖️ Comparison

| Feature | Nexus-Core | Synapse-Base |
|---------|------------|--------------|
| Speed | ⚡⚡⚡ Ultra-fast | ⚡⚡ Fast |
| Strength | 2000-2200 ELO | 2400-2600 ELO |
| Tactics | Basic | Advanced |
| Search Depth | 4-5 | 5-7 |
| Use Case | Online/Mobile | Tournament |

---

**Developed by:** [GambitFlow](https://huggingface.co/GambitFlow) / Rafsan1711  
**License:** CC BY-NC 4.0  
**Citation:**

```bibtex
@software{gambitflow_nexus_core_2025,
  author = {Rafsan1711},
  title = {Nexus-Core: Lightweight ResNet Chess Engine},
  year = {2025},
  publisher = {Hugging Face},
  url = {https://huggingface.co/GambitFlow/Nexus-Core}
}
```

---

Part of the **GambitFlow Project** 🚀♟️