USAGE_GUIDE.md

# How to Use the Advanced Magnus Chess Model from Hugging Face

## Quick Start Guide

Once your model is uploaded to Hugging Face, here's how others can use it:

### 1. Installation

```bash
pip install huggingface_hub torch chess numpy pyyaml scikit-learn
```

### 2. Download and Use the Model

```python
from huggingface_hub import hf_hub_download
import chess
import sys
import os

# Download model files (replace YOUR_USERNAME with your actual username)
repo_id = "YOUR_USERNAME/advanced-magnus-chess-model"

# Download required files
model_path = hf_hub_download(repo_id=repo_id, filename="model.pth")
predictor_path = hf_hub_download(repo_id=repo_id, filename="advanced_magnus_predictor.py")
config_path = hf_hub_download(repo_id=repo_id, filename="config.yaml")

# Add the download directory to Python path
download_dir = os.path.dirname(model_path)
sys.path.append(download_dir)

# Import and use the predictor
from advanced_magnus_predictor import AdvancedMagnusPredictor

# Initialize the predictor
predictor = AdvancedMagnusPredictor()

# Analyze a chess position
board = chess.Board("rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1")
predictions = predictor.predict_moves(board, top_k=5)

print("Magnus-style move predictions:")
for i, pred in enumerate(predictions, 1):
    move = pred['move']
    confidence = pred['confidence']
    san = board.san(chess.Move.from_uci(move))
    print(f"{i}. {san} ({move}) - {confidence:.3f} confidence")
```

### 3. Example Output

```
Magnus-style move predictions:
1. c5 (c7c5) - 0.145 confidence
2. e5 (e7e5) - 0.123 confidence
3. Nf6 (g8f6) - 0.098 confidence
4. d6 (d7d6) - 0.087 confidence
5. e6 (e7e6) - 0.075 confidence
```

## Advanced Usage

### Batch Analysis

```python
positions = [
    "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1",
    "rnbqkbnr/pp1ppppp/8/2p5/4P3/8/PPPP1PPP/RNBQKBNR w KQkq c6 0 2",
    "rnbqkbnr/ppp1pppp/8/3p4/2PP4/8/PP2PPPP/RNBQKBNR b KQkq c3 0 2"
]

for i, fen in enumerate(positions):
    print(f"\nPosition {i+1}: {fen}")
    board = chess.Board(fen)
    predictions = predictor.predict_moves(board, top_k=3)

    for pred in predictions:
        san = board.san(chess.Move.from_uci(pred['move']))
        print(f"  {san}: {pred['confidence']:.3f}")
```

### Integration with Chess Engines

```python
import chess.engine

# Combine Magnus predictions with Stockfish analysis
stockfish = chess.engine.SimpleEngine.popen_uci("/path/to/stockfish")

board = chess.Board("your_position_fen")

# Get Magnus-style predictions
magnus_predictions = predictor.predict_moves(board, top_k=5)

# Get engine analysis
engine_result = stockfish.play(board, chess.engine.Limit(time=1.0))
engine_move = engine_result.move.uci()

print("Magnus predictions vs Engine:")
for pred in magnus_predictions:
    move = pred['move']
    san = board.san(chess.Move.from_uci(move))
    marker = " ⭐" if move == engine_move else ""
    print(f"  {san}: {pred['confidence']:.3f}{marker}")

stockfish.quit()
```

## Model Features

-   **Style Emulation**: Predicts moves in Magnus Carlsen's characteristic style
-   **High Accuracy**: 6.65% exact match, 14.17% top-5 accuracy
-   **Fast Inference**: ~50ms per position
-   **Comprehensive**: Handles all chess positions and game phases
-   **Educational**: Perfect for learning Magnus's strategic concepts

## Use Cases

1. **Chess Training**: Learn Magnus's move preferences
2. **Game Analysis**: Understand Magnus-style thinking
3. **AI Development**: Building chess applications
4. **Research**: Studying player-specific chess styles
5. **Educational Tools**: Teaching advanced chess concepts

## Technical Notes

-   Model requires position feature extraction
-   Works best with properly formatted FEN strings
-   Optimized for modern hardware (GPU/MPS supported)
-   Compatible with standard chess libraries

## Support

For issues or questions about using the model, please check the model repository on Hugging Face or create an issue in the original project repository.

## Citation

```bibtex
@misc{advanced_magnus_chess_model_2025,
  title={Advanced Magnus Carlsen Chess Model},
  author={Chess AI Research Team},
  year={2025},
  url={https://huggingface.co/YOUR_USERNAME/advanced-magnus-chess-model}
}
```