Update README.md

README.md

@@ -1,6 +1,6 @@
 ---
 title: Nexus-Core Inference API
-emoji: ⚡
+emoji: ♟️
 colorFrom: green
 colorTo: blue
 sdk: docker
@@ -8,58 +8,72 @@ pinned: false
 license: cc-by-nc-4.0
 ---
 
-# ⚡ Nexus-Core Inference API
+# ♟️ Nexus-Core: Deep Search Chess Engine
 
-Fast and efficient chess move prediction powered by Nexus-Core v2.0.
+![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--20-red)
 
-[![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)
+**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
+---
 
-**Nexus-Core** is a lightweight ResNet-based chess engine optimized for speed:
+## 🎯 Model Details
 
-- **Model:** [GambitFlow/Nexus-Core](https://huggingface.co/GambitFlow/Nexus-Core)
-- **Parameters:** 13 Million
-- **Architecture:** Pure CNN (ResNet with 10 blocks)
+- **Architecture:** Pure CNN (ResNet-20 backbone)
+- **Parameters:** 13,242,433
 - **Input:** 12-channel board representation
-- **Training Data:** [GambitFlow/Elite-Data](https://huggingface.co/datasets/GambitFlow/Elite-Data) (5M+ positions)
-- **Strength:** 2000-2200 ELO estimated
+- **Training Data:** 5M+ elite positions (2000+ ELO)
+- **Model Hub:** [GambitFlow/Nexus-Core](https://huggingface.co/GambitFlow/Nexus-Core)
+
+---
 
-## 🔬 Search Algorithm
+## 🚀 Features
 
-Efficient alpha-beta implementation with essential optimizations:
+### 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
 
-### 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 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
 
-### Move Ordering
-- **MVV-LVA** [^4] - Most Valuable Victim - Least Valuable Attacker
-- **Promotion prioritization**
-- **Check detection**
+### 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
+---
+
+## 📊 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 |
 
-| 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 |
+*Benchmarked on HF Spaces CPU (2 vCPU, 16GB RAM)*
+
+---
 
-## 📡 API Endpoints
+## 📡 API Usage
 
-### `POST /get-move`
+### Endpoint: `POST /get-move`
 
 **Request:**
 ```json
 {
   "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
-  "depth": 4,
+  "depth": 5,
   "time_limit": 3000
 }
 ```
@@ -68,98 +82,163 @@ Efficient alpha-beta implementation with essential optimizations:
 ```json
 {
   "best_move": "e2e4",
-  "evaluation": 0.21,
-  "depth_searched": 4,
-  "nodes_evaluated": 8432,
-  "time_taken": 856
+  "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
 }
 ```
 
-### `GET /health`
+### Parameters
 
-Health check endpoint.
+| 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 |
 
-## 🔧 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)
+## 🏗️ Architecture
 
-## 🚀 Quick Start
+### Modular Design
 
-```python
-import requests
+```
+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)
+```
 
-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
-    }
-)
+### Search Flow
 
-data = response.json()
-print(f"Best move: {data['best_move']}")
-print(f"Evaluation: {data['evaluation']}")
 ```
+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
 
-## 💻 Use Cases
+This engine implements state-of-the-art techniques from:
 
-Perfect for:
-- **Online chess platforms** - Fast response times
-- **Training applications** - Consistent ~2000 ELO play
-- **Mobile apps** - Lightweight inference
-- **Rapid/Blitz games** - Quick move generation
+1. **Alpha-Beta Pruning**
+   - Knuth, D. E., & Moore, R. W. (1975). *An analysis of alpha-beta pruning*. Artificial Intelligence, 6(4), 293-326.
 
-## 📚 Research References
+2. **Principal Variation Search**
+   - Marsland, T. A. (1986). *A Review of Game-Tree Pruning*. ICCA Journal, 9(1), 3-19.
 
-[^1]: **Alpha-Beta Pruning**: Knuth, D. E., & Moore, R. W. (1975). "An analysis of alpha-beta pruning". *Artificial Intelligence*, 6(4), 293-326.
+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.
 
-[^2]: **Iterative Deepening**: Korf, R. E. (1985). "Depth-first iterative-deepening: An optimal admissible tree search". *Artificial Intelligence*, 27(1), 97-109.
+4. **Late Move Reductions**
+   - Heinz, E. A. (2000). *Adaptive null-move pruning*. ICCA Journal, 23(3), 123-134.
 
-[^3]: **Quiescence Search**: Shannon, C. E. (1950). "Programming a computer for playing chess". *Philosophical Magazine*, 41(314), 256-275.
+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.
 
-[^4]: **MVV-LVA**: Hyatt, R. M., Gower, A. E., & Nelson, H. L. (1990). "Cray Blitz". *Computers, Chess, and Cognition*, 111-130.
+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.
 
-## 📖 Related Work
+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.
 
-- **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/
+8. **Quiescence Search**
+   - Harris, L. R. (1975). *The heuristic search under conditions of error*. Artificial Intelligence, 5(3), 217-234.
 
-## 🏆 Model Lineage
+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.
 
-**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
+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.
 
-## ⚖️ 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 |
+## ⚙️ System Requirements
+
+- **CPU:** 2+ cores recommended
+- **RAM:** 4GB minimum, 8GB recommended
+- **Storage:** 500MB for model + cache
 
 ---
 
-**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}
-}
+## 🔧 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}'
 ```
 
 ---
 
-Part of the **GambitFlow Project** 🚀♟️
+## 📈 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
+
+CC BY-NC 4.0 - Non-commercial use only
+
+---
+
+## 🙏 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*