Hugging Face's logo

Spaces:
GambitFlow
/
Nexus-Core-Inference-api
Sleeping

App Files Community
Nexus-Core-Inference-api / README.md
Rafs-an09002's picture
Rafs-an09002
Update README.md
837b25b verified
preview code
|
raw
history blame contribute delete
7.04 kB
metadata
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 Model Size Architecture

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

🚀 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:

{
  "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
  "depth": 5,
  "time_limit": 3000
}

Response:

{
  "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 

# 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

  • PVS search implementation
  • Transposition table with Zobrist hashing
  • Advanced move ordering (killer + history)
  • 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