README.md

---
title: Chess Engine with Stockfish Integration
emoji: ♟️
colorFrom: green
colorTo: indigo
sdk: docker
sdk_version: "latest"
app_file: app.py
app_port: 8000
pinned: false
---



A Python chess engine with Stockfish integration, providing both a command-line interface and a REST API for playing chess against an AI opponent.

## Features

- **AI Integration**: Play against Stockfish, one of the strongest chess engines available
- **Multiple Interfaces**:
  - Command-line interface for quick games
  - REST API for integration with web or desktop applications
  - Streamlit web interface for graphical gameplay
- **Adjustable Difficulty**: Six difficulty levels from beginner to master
- **Position Analysis**: Get detailed evaluation of board positions
- **Move Hints**: Receive suggestions and explanations for optimal moves
- **Notation Support**: Works with both UCI (e2e4) and SAN (e4) chess notations
- **Game Management**: Start, play, analyze, and save games
- **Comprehensive Evaluation**: Material balance, piece positioning, king safety, mobility, and pawn structure

## Requirements

- Python 3.8+
- Stockfish chess engine (optional, but recommended for AI play)
- Dependencies listed in requirements.txt


## API Documentation

For information please refer Dockerfile

### Example API Usage

Start a new game:
```bash
curl -X POST "http://localhost:8000/game/new" \
  -H "Content-Type: application/json" \
  -d '{"player_color": "white", "difficulty": "medium"}'
```

Make a move:
```bash
curl -X POST "http://localhost:8000/game/move" \
  -H "Content-Type: application/json" \
  -d '{"move": "e2e4"}'
```

Get current game state:
```bash
curl -X GET "http://localhost:8000/game/state"
```

## Testing

Run the test suite:

```bash
python test/run_tests.py
```

For more detailed output:

```bash
python test/run_tests.py -v
```

The test suite includes:
- Board representation and move validation tests
- Position evaluation tests
- Game controller tests
- REST API endpoint tests

## License

### Code
The code in this repository is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

### Assets
The chess piece images and board square assets are licensed under the Creative Commons Attribution-ShareAlike (CC-BY-SA) license. See the [LICENSE-ASSETS.md](LICENSE-ASSETS.md) file for details on attribution and compliance requirements.

**Note:** If you redistribute this project or create derivative works, you must comply with both licenses - MIT for the code and CC-BY-SA for the assets.