README.md

---
title: Nexus-Nano Inference API
emoji: 🚀
colorFrom: yellow
colorTo: red
sdk: docker
pinned: false
license: cc-by-nc-4.0
---

# 🚀 Nexus-Nano Inference API

Ultra-lightweight chess engine for instant responses.

[![Model](https://img.shields.io/badge/Model-Nexus--Nano-yellow)](https://huggingface.co/GambitFlow/Nexus-Nano)
[![Parameters](https://img.shields.io/badge/Params-2.8M-orange)](https://huggingface.co/GambitFlow/Nexus-Nano)
[![Speed](https://img.shields.io/badge/Speed-Lightning-red)](https://huggingface.co/GambitFlow/Nexus-Nano)

## 🎯 Model Details

**Nexus-Nano** is the fastest model in the GambitFlow series:

- **Model:** [GambitFlow/Nexus-Nano](https://huggingface.co/GambitFlow/Nexus-Nano)
- **Parameters:** 2.8 Million
- **Architecture:** Compact ResNet (6 blocks)
- **Input:** 12-channel board representation
- **Training Data:** [GambitFlow/Elite-Data](https://huggingface.co/datasets/GambitFlow/Elite-Data) (5M+ positions)
- **Strength:** 1800-2000 ELO estimated

## 🔬 Search Algorithm

Ultra-minimal implementation for maximum speed:

### Core Features
- **Pure Alpha-Beta Pruning** [^1] - Classic minimax
- **Simple MVV-LVA Ordering** [^2] - Capture prioritization
- **No Transposition Table** - Zero memory overhead
- **Iterative Deepening** - Anytime algorithm

### Design Philosophy
- **Single-file engine** - No modular complexity
- **Minimal overhead** - Direct evaluation calls
- **Speed over strength** - Optimized for response time

## 📊 Performance

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

## 📡 API Endpoints

### `POST /get-move`

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

**Response:**
```json
{
  "best_move": "e2e4",
  "evaluation": 0.18,
  "depth_searched": 3,
  "nodes_evaluated": 2847,
  "time_taken": 234
}
```

### `GET /health`

Health check endpoint.

## 🔧 Parameters

- **fen** (required): Board position in FEN notation
- **depth** (optional): Search depth (1-5, default: 3)

## 🚀 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": 3
    }
)

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

## 💻 Use Cases

Perfect for:
- **Bullet chess (1+0, 2+1)** - Lightning-fast moves
- **Chess tutorials** - Instant move suggestions
- **Mobile applications** - Minimal resource usage
- **Live analysis** - Real-time position evaluation
- **Casual play** - Good enough for beginners/intermediate

## 📚 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]: **MVV-LVA**: Hyatt, R. M., Gower, A. E., & Nelson, H. L. (1990). "Cray Blitz". *Computers, Chess, and Cognition*, 111-130.

## 📖 Minimalist Design Inspiration

- **MicroMax** - Mulder, H. G. (2007). "1433-byte chess program". https://home.hccnet.nl/h.g.muller/max-src2.html
- **Sunfish** - Fiekas, N. (2013). "Simple chess engine in Python". https://github.com/thomasahle/sunfish
- **Stockfish Lite** - Simplified versions for embedded systems

## 🏆 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 Table

| Feature | Nexus-Nano | Nexus-Core | Synapse-Base |
|---------|------------|------------|--------------|
| **Speed** | ⚡⚡⚡⚡ Lightning | ⚡⚡⚡ Ultra-fast | ⚡⚡ Fast |
| **Strength** | 1800-2000 ELO | 2000-2200 ELO | 2400-2600 ELO |
| **Memory** | 1GB | 2GB | 5GB |
| **Depth** | 3-4 | 4-5 | 5-7 |
| **Response** | 200-500ms | 500-1000ms | 1000-2000ms |
| **Best for** | Bullet/Mobile | Online/Rapid | Tournament/Analysis |

## 🎯 When to Use

Choose **Nexus-Nano** if:
- ✅ Speed is critical (bullet games, live demos)
- ✅ Resource-constrained environment (mobile, embedded)
- ✅ Playing against beginners/intermediate (1800-2000 ELO)
- ✅ You need instant move suggestions

Choose **Nexus-Core** if:
- ⚡ You want balanced speed and strength
- ⚡ Playing online rapid/blitz games

Choose **Synapse-Base** if:
- 🏆 Maximum strength is priority
- 🏆 Tournament-level play
- 🏆 Deep position analysis needed

---

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

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

---

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